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Preface 


Intended Audience 


This manual is intended for system programmers who want to take advantage of the time and space savings 
that result from direct use of I/O drivers. OpenVMS users who do not require such detailed knowledge of I/O 
drivers can use the device-independent servicdes described in the OpenVMS Record Management Services 
Reference Manual. 


Document Structure 
This manual is organized into the following chapters and appendixes: 


e Chapter 1 describes the Queue I/O (QIO) interface to file system ancillary control processes (ACPs). 


e Chapters 2 through 9 describe the use of file-structured and real-time I/O device drivers, the drivers for 
storage devices such as disks and magnetic tapes, and supported terminal devices: 


— Chapter 2 discusses the disk drivers. 
— Chapter 3 discusses the magnetic tape drivers. 
— Chapter 4 discusses the mailbox driver. 
— Chapter 5 discusses the terminal driver. 
— Chapter 6 discusses the pseudoterminal driver. 
— Chapter 7 discusses the shadow-set virtual unit driver. 
— Chapter 8 discusses the Generic Small Computer System Interface (SCSD class driver. 
— Chapter 9 discusses the local area network (LAN) device drivers. 
e Chapter 10 describes optional features to improve OpenVMS Alpha I/O performance. 


e Appendix A summarizes the QIO function codes, arguments, and function modifiers used by the drivers 
listed previously. 


e Appendix B describes the enhanced IO$_DIAGNOSE function for SCSI class drivers. 


e Appendix C lists the DEC Multinational character set and the ANSI and DIGITAL private escape 
sequences for terminals. 


e Appendix D describes the calling conventions for the pseudoterminal driver's control connection routines. 


Device Driver Support for OpenVMS Alpha and 164 64-Bit Addressing 


The OpenVMS Alpha and 164 operating systems provide support for 64-bit virtual memory addressing, which 
makes the 64-bit virtual address space defined by the architecture available to the OpenVMS Alpha and 164 
operating systems and to application programs. In the 64-bit virtual address space, both process-private and 
system virtual address space extend beyond 2 GB. By using 64-bit addressing features, programmers can 
create images that map and access data beyond the limits of 32-bit virtual addresses. 


Input and output operations can be performed directly to and from the 64-bit addressable space by means of 
RMS services, the $QIO system service, and most of the device drivers supplied with OpenVMS Alpha and 
164 systems. A device driver declares support for 64-bit addresses individually by I/O function code. Disk and 
tape device drivers support 64-bit addresses for data transfers to and from disk and tape devices on the 
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virtual, logical, and physical read and write functions. For example, the OpenVMS SCSI disk class driver, 
SYS$DKDRIVER, supports 64-bit addresses on the IO$_READVBLK and IO$_WRITEVBLK functions, but 
not on the IO$_AUDIO function. The device drivers, function codes, and $QIO arguments that support 64-bit 
addressing are indicated in the appropriate chapters of this manual. 


For more information about the OpenVMS device drivers that support 64-bit addressing, see the HP 
OpenVMS Programming Concepts Manual. To find out how to modify a customer-written device driver to 
support 64-bit addressing, see the HP OpenVMS Guide to Upgrading Privileged-Code Applications Manual. 


Related Documents 

The following manuals provide additional information that relates to the topics covered in this book: 
e HP OpenVMS Guide to Upgrading Privileged-Code Applications 

e HP OpenVMS Programming Concepts 

e HP OpenVMS System Services Reference Manual: A-GGETUAI 

e HP OpenVMS System Services Reference Manual: GETUTC-Z 

e OpenVMS Record Management Services Reference Manual 

e DECnet for OpenVMS Guide to Networking (available on the Documentation CD-ROM) 

e OpenVMS VAX Device Support Manual (available on the Documentation CD-ROM) 


NOTE For updated hardware information, refer to the most recent Software Product Description for 
the OpenVMS Operating System (SPD 82.35.xx). 


Reader's Comments 
HP welcomes your comments on this manual. 
Please send comments to either of the following addresses: 


Internet: openvmsdoc@hp.com 


Postal Mail: 
Hewlett-Packard Company 
OSSG Documentation Group 
ZKO3-4/U08 

110 Spit Brook Road 
Nashua, NH 03062-2698 


How to Order Additional Documentation 


For information about how to order additional documentation, visit the following World Wide Web address : 


http: //www.hp.com/go/openvms/doc/order 


Conventions 
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The following conventions may be used in this manual: 


Convention 


Meaning 


Ctrl/x 


PF1 x 


Return 


bold type 


italic type 


UPPERCASE TYPE 


A sequence such as Ctrl/x indicates that you must hold down the key labeled 
Ctrl while you press another key or a pointing device button. 


A sequence such as PF 1 x indicates that you must first press and release the 
key labeled PF1 and then press and release another key (x) or a pointing 
device button. 


In examples, a key name in bold indicates that you press that key. 


A horizontal ellipsis in examples indicates one of the following possibilities: 


— Additional optional arguments in a statement have been omitted. 
— The preceding item or items can be repeated one or more times. 
— Additional parameters, values, or other information can be entered. 


A vertical ellipsis indicates the omission of items from a code example or 
command format; the items are omitted because they are not important to 
the topic being discussed. 


In command format descriptions, parentheses indicate that you must 
enclose choices in parentheses if you specify more than one. 


In command format descriptions, brackets indicate optional choices. You can 
choose one or more items or no items. Do not type the brackets on the 
command line. However, you must include the brackets in the syntax for 
OpenVMS directory specifications and for a substring specification in an 
assignment statement. 


In command format descriptions, vertical bars separate choices within 
brackets or braces. Within brackets, the choices are optional; within braces, 
at least one choice is required. Do not type the vertical bars on the command 
line. 


In command format descriptions, braces indicate required choices; you must 
choose at least one of the items listed. Do not type the braces on the 
command line. 


Bold type represents the introduction of a new term. It also represents the 
name of an argument, an attribute, or a reason. 


Italic type indicates important information, complete titles of manuals, or 
variables. Variables include information that varies in system output 
(Internal error number), in command lines (/PRODUCER=name), and in 
command parameters in text (where (dd) represents the predefined par code 
for the device type). 


Uppercase type indicates a command, the name of a routine, the name of a 
file, or the abbreviation for a system privilege. 
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Convention 


Meaning 


Example 


numbers 


This typeface indicates code examples, command examples, and interactive 
screen displays. In text, this type also identifies URLs, UNIX commands 
and pathnames, PC-based commands and folders, and certain elements of 
the C programming language. 


A hyphen at the end of a command format description, command line, or 
code line indicates that the command or statement continues on the 
following line. 


All numbers in text are assumed to be decimal unless otherwise noted. 
Nondecimal radixes—hbinary, octal, or hexadecimal—are explicitly 
indicated. 
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ACP-QIO Interface 


1 ACP-QIO Interface 


An ancillary control process (ACP) is a process that interfaces between the user process and the driver, 
and performs functions that supplement the driver's functions. Virtual I/O operations involving 
file-structured devices (disks and magnetic tapes) often require ACP intervention. In most cases, ACP 
intervention is requested by OpenVMS Record Management Services (RMS) and is transparent to the user 
process; however, user processes can request ACP functions directly by issuing a Queue I/O (QIO) request and 
specifying an ACP function code. 


Executing physical and logical input/output (I/O) operations on a device that is managed by a file ACP 
interferes with the operation of the ACP, and can result in unpredictable consequences such as system failure. 


In addition to the ACP, the XQP (extended QIO processor) facility supplements the QIO driver's functions 
when performing virtual I/O operations on file-structured devices; however, rather than being a separate 
process, the XQP executes as a kernel-mode thread in the process of its caller. 


An XQP is provided to support Files-11 ODS-2 and ODS-5 (On-Disk Structure Level 2 and 5) disks as the 
base file system, and an ACP is provided for ANSI standard X3.27 magnetic tapes. 


On VAX systems, an ACP is provided for supporting Files-11 ODS-1 (On-Disk Structure Level 1) disks. 


There are also ACPs to support the ISO 9660 CD-ROM disk structure (Files-11 C) and High Sierra CD-ROM 
disk structure (Files-11 D). Collectively, these ACPs are called Files-11 C/D. 


This chapter describes the QIO interface to ACPs for disk and magnetic tape devices (file system ACPs). The 
sample program in Chapter 10 performs QIO operations to the magnetic tape ACP. 


This chapter also describes a number of structures and field names of the form xxx$name. A MACRO program 
can define symbols of this form by invoking the $xxxDEF macro. 


The following macros are available in SYS$LIBRARY:STARLET.MLB: 
$IODEF 

$FIBDEF 

$ATRDEF 

$SBKDEF 

The following macros are available in SYS$LIBRARY:LIB.MLB: 
$FATDEF 

$DQFDEF 

$FCHDEF 


Programs written in BLISS-32 can use these symbols by referencing them and including the correct library, 
SYS$LIBRARY:STARLET.L32 (for the macros listed under SYS$LIBRARY:STARLET.MLB), and 
SYS$LIBRARY:LIB.L32 (for the macros listed under SYS$LIBRARY:LIB.MLB). 


References to ANSI refer to the American National Standard Magnetic Tape Labels and File Structures for 
Information Interchange, ANSI X3.27-1978. 
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ACP-QIO Interface 
ACP Functions and Encoding 


1.1 ACP Functions and Encoding 


Ancillary control process (ACP) functions can be expressed using seven function codes and four function 
modifiers. The function codes are: 


¢ IO$_CREATE—Creates a directory entry or file 

¢ I0$_ACCESS—Searches a directory for a specified file and accesses the file, if found 

e I10$_DEACCESS—Deaccesses a file and, if specified, writes the final attributes in the file header 
¢ I0$ MODIFY—Modifies the file attributes and file allocation 

¢ I0$_DELETE—Deletes a directory entry and file header 

¢ I0$_MOUNT—Informs the ACP when a volume is mounted; requires MOUNT privilege 

¢ I0$ ACPCONTROL—Performs miscellaneous control functions 


The function modifiers are: 

¢ IO$M_ACCESS—Opens a file on the user's channel 

¢ IO$M_CREATE—Creates a file 

¢ IO$M_DELETE—Deletes a file or marks it for deletion 
¢ IO0$M_DMOUNT—Dismounts a volume 


In addition to the function codes and modifiers, ACPs take five device- or function-dependent arguments, as 
shown in Figure 1-1. The first argument, P1, is the address of the file information block (FIB) descriptor. 
Section 1.2 describes the FIB in detail. 


The second argument, P2, is an optional argument used in directory operations. It specifies the address of the 
descriptor for the file name string to be entered in the directory. 


Argument P38 is the address of a word to receive the resultant file name string length. The resultant string is 
not padded. The actual length is returned in P3. Argument P4 is the address of a descriptor for a buffer to 
receive the resultant file name string. Both of these arguments are optional. 


Figure 1-1 ACP Device- or Function-Dependent Arguments 


P1: 


0 
i i ional) 
ional) 
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P2: 


P4: Address of Resultant String Descriptor (Optional 
P5: Address of Attribute Control Block (Optional 


ZK0636GE 
The fifth argument, P5, is an optional argument containing the address of the attribute control block. Section 


1.3.5 describes the attribute control block in detail. 


All areas of memory specified by the descriptors must be capable of being read or written to. 
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ACP-QIO Interface 
File Information Block (FIB) 


Figure 1-2 shows the format for the descriptors. The count field is the length in bytes of the item described. 


Figure 1-2 ACP Device/Function Argument Descriptor Format 


31 16 15 0 


Address 


ZK0637GE 


1.2 File Information Block (FIB) 


The file information block (FIB) contains much of the information that is exchanged between the user process 
and the ACP. The FIB must be writable. 


The FIB is passed by a descriptor (see Figure 1-2). A short FIB can be used in ACP calls that do not need 
arguments near the end of the FIB. The ACP treats the omitted portion of the FIB as if it were 0. Figure 1-3 
shows the format of a typical short FIB that would be used to open an existing file. 


Figure 1-3 Typical Short FIB 
31 24 23 16 15 87 0 


FIB$B_WSIZE FIB$L_ACCTL 


FIB$W_FID 


FIB$W_DID 


FIB$L_WCC 
+— 0 FIB$W_NMCTL 


+m 0 


ZK0639GE 


Table 1-1 gives a brief description of the FIB fields. More detailed descriptions are provided in Sections 
Section 1.3 and Section 1.6. 


Table 1-1 Contents of the FIB 


Field Meaning 


FIB$L_ACCTL Contains flag bits that control the access to the file. Sections Section 
1.3.1.1, Section 1.3.2.1, Section 1.6.1.1, and Section 1.6.4.1, and Section 
1.6.5 describe the FIB$L_ACCTL field flag bits. 
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File Information Block (FIB) 


Table 1-1 Contents of the FIB (Continued) 


Field Meaning 


FIB$L_ACL_STATUS Status of the requested ACL attribute operation, if any. The ACL 
attributes are included in Table 1-7. If no ACL attributes are given, 
SS$_NORMAL is returned here. 


FIB$L_ACLCTX Maintains position context when processing ACL attributes from the 
attribute (P5) list. 

FIB$B_ ALALIGN Contains the interpretation mode of the allocation (FIB$W_ALLOC) 
field. 

FIB$W_ALLOC Contains the desired physical location of the blocks being allocated. 


Interpretation of the field is controlled by the FIB$B_ALALIGN field. 
The following subfields are defined: 


Subfield Meaning 

FIB$W_LOC_FID Three-word related file ID for RFI 
placement. 

FIB$W_LOC_NUM Related file number. 

FIB$W_LOC_SEQ Related file sequence number. 

FIB$B_LOC_RVN Related file relative volume number 
(RVN) or placement RVN. 

FIB$B_LOC_NMX Related file number extension. 

FIB$L_LOC_ADDR Placement logical block number (LBN), 
cylinder, or virtual block number (VBN). 

FIB$B_ALOPTS Contains option bits that control the 


placement of allocated blocks. Section 
1.3.3.1 describes the FIB$B_ALOPTS 
field flag bits. 


FIB$L_ALT_ACCESS A 32-bit mask that represents an access mask to check against file 
protection; for example, opens a file for read access and checks whether 
it can be deleted. The mask has the same configuration as the standard 
protection mask. 


FIB$W_CNTRLFUNC In an 1IO$_-ACPCONTROL function, this field contains the code that 
specifies which ACP control function is to be performed (see Section 
1.6.8). This field overlays FIB$W_EXCTL. 


FIB$L_CNTRLVAL Contains a control function value used in an IO$_ ACPCONTROL 
function (see Section 1.6.8). The interpretation of the value depends on 
the control function specified in FIBSW_CNTRLFUNC. This field 
overlays FIB$L_EXSZ. 
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Table 1-1 


ACP-QIO Interface 
File Information Block (FIB) 


Contents of the FIB (Continued) 


Field 


Meaning 


FIB$W_DID 


FIB$W_EXCTL 


FIB$L_EXSZ 


FIB$L_EXVBN 


FIB$W_FID 


Contains the file identifier of the directory file. 


For Files-11 On-Disk Structure Level 1 and Level 2, the following 
subfields are defined: 


Subfield Meaning 

FIB$W_DID_NUM File number. 

FIB$W_DID_SEQ File sequence number. 

FIB$W_DID_RVN Relative volume number (only for 
magnetic tape devices). 

FIB$B_DID_RVN Relative volume number (only for disk 
devices). 

FIB$B_DID_NMX File number extension (only for disk 
devices). 


Contains flag bits that specify extend control for disk devices. Sections 
Section 1.3.3.1 and Section 1.3.4.1 describe the FIB$W_EXCTL field 
flag bits. 


Specifies the number of blocks to be allocated in an extend operation on 
a disk file. 


Specifies the starting disk file virtual block number at which a file is to 
be truncated. 


Specifies the file identification. You supply the file identifier when it is 
known; the ACP returns the file identifier when it becomes known; for 
example, as a result of a create or directory lookup. A 0 file identifier 
can be specified when an operation is performed on a file that is already 
open on a particular channel. The ACP returns the file identifier of the 
open file. 


For Files-11 On-Disk Structure Level 1 and Level 2, the following 
subfields are defined: 


Subfields Meaning 

FIB$W_FID_NUM File number. 

FIB$W_FID_SEQ File sequence number. 

FIB$W_FID_RVN Relative volume number (only for 
magnetic tape devices). 

FIB$B_FID_RVN Relative volume number (only for disk 
devices). 

FIB$B_FID_NMX File number extension (only for disk 
devices). 
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File Information Block (FIB) 


Table 1-1 Contents of the FIB (Continued) 


Field 


Meaning 


FIB$B_NAME_FORMAT_IN 


FIB$B_NAME_ FORMAT OUT 


FIB$W_NMCTL 


FIB$L_STATUS 
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FIB$W_FID_DIRNUM 


FIB$L_FID_RECNUM 


Directory number of the file identifier. 
This is the path table record number of 
the directory that describes the file. 


Record number of the first directory 
record for the file within the current 
directory. 


Contains the format of the input file specification. Section 1.3.1.1 
describes the FIB$B_NAME_FORMAT_IN field flag bits. 


Contains the format of the output file specification. Section 1.3.1.1 
describes the FIB$B_NAME_FORMAT_OUT field flag bits. 


Contains flag bits that control the processing of a name string in a 
directory operation. Sections Section 1.3.1.1 and Section 1.6.1.1 
describe the FIB$W_NMCTL field flag bits. 


Access status. Applies to all major functions. The following bits are 


supported: 
Subfields 
FIB$V_ALT_REQ 


FIB$V_ALT_GRANTED 


FIB$V_DIRACL 


FIB$V_EXCLPREVIOUS 


FIB$V_ALIAS ENTRY 


Meaning 


Set to indicate whether the alternate 
access bit is required for the current 
operation. If not set, the alternate access 
bit is optional. 


If FIB$V_ALT_REQ = 0, the FIB bit 
returned from the file system is set if the 
alternate access check succeeded. 


Programmers can control the security 
information being propagated as well as 
the source of this information by setting 
the following bits (which apply only to the 
IO0$_CREATE and I0$_MODIFY 
functions). 


Propagate the ACL from the parent 
directory to the file, assuming the file is a 
directory file. 


Set to indicate that propagation may not 
occur from a previous version of the file. 


Set on any file system operation where 
the directory backlink in the file header is 
different (and nonzero) from the directory 
id specified in the FIB. 


Table 1-1 


Contents of the FIB (Continued) 


ACP-QIO Interface 
ACP Subfunctions 


Field 


Meaning 


FIB$W_VERLIMIT 
FIB$L_WCC 


FIB$B_WSIZE 


FIB$V_NOCOPYACL 


FIB$V_NOCOPYOWNER 


FIB$V_NOCOPYPROT 


FIB$V_PROPAGATE 


Set to indicate that the ACL should not be 
propagated from the parent directory (or a 
previous version of the file) to the file. 


Set to indicate that the owner UIC should 
not be propagated from the parent 
directory (or a previous version of the file) 
to the file. 


Set to indicate that the UIC-based 
protection should not be propagated from 


the parent directory (or a previous version 
of the file) to the file. 


Propagate attributes from the parent 
directory (or previous version of the file). 
If you set the FIB$V_NOCOPYACL, 
FIB$V_NOCOPYOWNER, or 
FIB$V_NOCOPYPROT bits, you must 
also set FIB$¢V_PROPAGATE or a 
SS$_BADPARAM error results. 


Contains the version limit of the directory entry. 


Maintains position context when processing wildcard directory 


operations. 


Controls the size of the file window used to map a disk file. If a window 
size of 255 is specified, the file is completely mapped by using 


segmented windows. 


1.3 ACP Subfunctions 


The operations that the ACP performs can be organized into two categories: major ACP functions and 
subfunctions. Each ACP operation performs one major function. That function is specified by an I/O function 
code, such as IO$_ACCESS, IO$_CREATE, or IO$_MODIFY. While executing the major function, one or more 
subfunctions can be performed. A subfunction is an operation such as looking up, accessing, or extending a 
file. Most subfunctions can be executed by more than one of the major functions. Sections Section 1.3.1 
through Section 1.3.5 describe the following subfunctions in detail: 


Directory Lookup 


Access 
Extend 


Truncate 


Read/Write Attributes 
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Section 1.6, which contains the descriptions of the major functions, lists the subfunctions available to each 
major function. 


1.3.1 Directory Lookup 


The directory lookup subfunction is used to search for a file in a disk directory or on a magnetic tape. This 
subfunction can be invoked using the major functions IO$_ACCESS, IO0$_MODIFY, IO$_DELETE, and 
I0$_ACPCONTROL. A directory lookup occurs if the directory file ID field in the FIB (FIB$W_DID) is a 
nonzero number. 


1.3.1.1 Input Parameters 
Table 1-2 lists the FIB fields that control the processing of a lookup subfunction. 


Table 1-2 FIB Fields (Lookup Control) 
Field Subfields Meaning 
FIB$W_NMCTL Name string control. The following name 

control bits are applicable to a lookup 
operation: 

FIB$V_ALLNAM Set to match all name field values. 

FIB$V_ALLTYP Set to match all field type values. 

FIB$V_ALLVER Set to match all version field values. 


FIB$V_CASE_SENSITIVE When set, performs case-sensitive 
lookup; when clear, performs case-blind 


lookup. 

FIB$V_FINDFID Set to search a directory for the file ID in 
FIB$W_FID. 

FIB$V_NAMES_8BIT Caller can accept (8-bit) ODS-2 or ISO 
Latin-1 formats. 

FIB$V_NAMES_16BIT Caller can accept (16-bit) Unicode 
(UCS-2) formats. 

FIB$V_WILD Set if name string contains wildcards. 


Setting this bit causes wildcard context 
to be returned in FIB$L_WCC. 


FIB$W_FID File identification. The file ID of the file 
found is returned in this field. 
FIB$W_DID Contains the file identifier of the 


directory file. This field must be a 
nonzero number. 


FIB$L_WCC Maintains position context when 
processing wildcard directory operations. 


FIB$L_ACCTL The following access control flag is 
applicable to a lookup subfunction: 
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ACP Subfunctions 
Table 1-2 FIB Fields (Lookup Control) (Continued) 
Field Subfields Meaning 
FIB$V_REWIND Set to rewind magnetic tape before 


lookup. If not set, a magnetic tape is 
searched from its current position. 


FIB$B_NAME_FORMAT_IN Contains the format of the input file 
specification. The following formats are 
valid: 

FIB$C_ODS2 ODS-2 Format (default) 
FIB$C_ISO_ LATIN ISO Latin-1 Format 
FIB$C_UCS2 Unicode (UCS-2) Format 

FIB$B_NAME_FORMAT_OUT Contains the format of the output file 
specification. The following formats are 
valid: 

FIB$C_ODS2 ODS-2 Format (default) 
FIB$C_ISO_ LATIN ISO Latin-1 Format 
FIB$C_UCS2 Unicode (UCS-2) Format 


QIO arguments P2 through P5 (see Figure 1-1) are passed as values. The second argument, P2, specifies the 
address of the descriptor for the file name string to be searched for in the directory. 


The file name string must have one of the following two formats: 
name.type; version name.type.version 


The name and type can be any combination of alphanumeric characters, and the dollar sign ($), asterisk (*), 
and percent(%) characters. The version must consist of numeric characters optionally preceded by a minus 
sign (-) (only for disk devices) or a single asterisk. The total number of alphanumeric and percent characters 
in the name field and in the type field must not exceed 39. Any number of additional asterisks can be present. 


If any of the bits FIB$V_ALLNAM, FIB$V_ALLTYP, and FIB$V_ALLVER are set, then the contents of the 
corresponding field in the name string are ignored and the contents are assumed to be an asterisk. 


Note that the file name string cannot contain a directory string. The directory is specified by the FIB$W_DID 
field (see Table 1-2). Only RMS can process directory strings. 


Argument P3 is the address of a word to receive the resultant file name string length. Argument P4 is the 
address of a descriptor for a buffer to receive the resultant file name string. The resultant string is not 
padded. The P3 and P4 arguments are optional. 


1.3.1.2 Operation 


The system searches either the directory file specified by FIB$W_DID or the magnetic tape for the file name 
specified in the P2 file name parameter. The actual file name found and its length are returned in the P3 and 
P4 length and result string buffers. The file ID of the file found is returned in FIB$W_FID and can be used in 
subsequent operations as the major function is processed. 
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Zero and negative version numbers have special significance in a disk lookup operation. Specifying 0 as a 
version number causes the latest version of the file to be found. Specifying -1 locates the second most recent 
version, -2 the third most recent, and so forth. Specifying a version of -0 locates the lowest numbered version 
of the file. For magnetic tape lookups, a version number of 0 locates the first occurrence of the file 
encountered; negative version numbers are not allowed. 


Wildcard lookups are performed by specifying the appropriate wildcard characters in the name string and 
setting FIB$V_WILD. (The name control bits FIB$V_ALLNAM, FIB$V_ALLTYP, and FIB$V_ALLVER can 
also be used in searching for wildcard entries, but they are intended primarily for compatibility mode use.) On 
the first lookup, FIB$L_WCC should contain zero entries. On each lookup, the ACP returns a nonzero value 
in FIB$L_WCC, which must be passed back on the next lookup call. In addition, you must pass the resultant 
name string returned by the previous lookup using the P4 result string buffer, and its length in the P3 result 
length word. This string is used together with FIB$L_WCC to continue the wildcard search at the correct 
position in the directory. 


To perform a lookup by file ID, set the name control bit FIB$V_FINDFID. When this bit is set, the system 
searches the directory for an entry containing the file ID specified in FIB$W_FID, and the name of the entry 
found is returned in the P3 and P4 result parameters. Note that if a directory contains multiple entries with 
the same file ID, only the first entry can be located with this technique. 


Lookups by file ID should be done only when the file name is not available, because lookups by this method 
are often significantly slower than lookups by file name. 


Because not all programs can handle all of the available name formats, the FIB$W_NMCTL flags govern the 
name formats, and are returned as follows: 


e FIB$V_NAMES 8BIT clear 
FIB$V_NAMES_16BIT clear 


Only ODS-2 format names are returned. Note that this includes specifications that were originally in ISO 
Latin-1 format or Unicode (UCS-2) format but converted to ODS-2 format before being stored on the 
volume. All specifications are converted to uppercase before being returned. 


e FIB$V_NAMES 8BIT set 
FIB$V_ NAMES _16BIT clear 


Only those file specifications stored in ODS-2 and ISO Latin-1 formats are returned. The value in the 
FIB$B_NAME_FORMAT_OUT field indicates the format of the particular name being returned. ODS-2 
format file specifications are not converted to uppercase before being returned. 


e FIB$V_NAMES 8BIT clear 

FIB$V_ NAMES_16BIT set 

All file specifications are returned in Unicode (UCS-2) format. 
e FIB$V_NAMES 8BIT set 

FIB$V_ NAMES_16BIT set 


File specifications are returned in the format stored on the volume. This is the simplest format compatible 
with the file name syntax and the characters it contains. For example, a specification originally in 
Unicode format that only contains characters that are part of the ISO Latin-1 character set are returned 
in ISO Latin-1 format. 
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1.3.1.3. Directory Entry Protection 


A directory entry is protected with the same protection code as the file itself. For example, if a directory file is 
protected against delete access, then the file name has the same protection. Consequently, a nonprivileged 
user (that is, a user who is not the volume owner, or a user who does not have SYSPRV) cannot rename a file 
because renaming a file is essentially the same as deleting the file name. This protection is applied regardless 
of the protection on the directory file. 


Nonprivileged users can neither write directly into a .DIR;1 directory file nor turn off the directory bit in a 
directory file header. 


1.3.2 Access 


The access subfunction is used to open a file so that virtual read or write operations can be performed. This 
subfunction can be invoked using the major functions IO$_CREATE and IO$_ACCESS (see Section 1.6.1 and 
Section 1.6.2). An access subfunction is performed if the IO$M_ACCESS modifier is specified in the I/O 
function code. 


1.3.2.1 Input Parameters 


Table 1-3 lists the FIB fields that control the processing of an access subfunction. 


Table 1-3 FIB Fields (Access Control) 
Field Subfields Meaning 
FIB$L_ACCTL Specifies field values that control access to the file. The 
following access control bits are applicable to the access 
subfunction: 
FIB$V_WRITE Set for write access; clear for read-only access. 
FIB$V_NOREAD Set to deny read access to others. (You must have write 


privilege to the file to use this option.) 
FIB$V_NOWRITE Set to deny write access to others. 


FIB$V_NOTRUNC Set to prevent the file from being truncated; clear to allow 
truncation. 


FIB$V_CONTROL Set for control access. If this bit is set, you cannot access 
the file if you do not have control access. 


FIB$V_NO_READ____ Set to deny read access to the file. 
DATA 


FIB$V_DLOCK Set to enable deaccess lock (close check). Used only for 
disk devices. 


Used to flag a file as inconsistent if the program currently 
modifying the file terminates abnormally. If the program 
deaccesses the file without performing a write attributes 
operation, the file is marked as locked and cannot be 
accessed until it is unlocked. 


FIB$V_UPDATE Set to position at the start of a magnetic tape file when 
opening a file for write; clear to position at end-of-file. 
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Table 1-3 FIB Fields (Access Control) (Continued) 


Field Subfields Meaning 


FIB$V_READCK Set to enable read checking of the file. Virtual reads to 
the file are performed using a data check operation. 


FIB$V_WRITECK Set to enable write checking of the file. Virtual writes to 
the file are performed using a data check operation. 


FIB$V_EXECUTE Set to access the file in execute mode. The protection 
check is made against the EXECUTE bit instead of the 
READ bit. Valid only for requests issued from 
SUPERVISOR, EXEC, or KERNEL mode. 


FIB$V_NOLOCK Set to override exclusive access to the file, allowing you to 
access the file when another user has the file open with 
FIB$V_NOREAD specified. You must have SYSPRV 
privilege to use this option. FIB$V_NOREAD and 
FIB$V_NOWRITE must be clear for this option to work. 


You must have either SYSPRV privilege or control access 
to use this option. 


FIB$V_NORECORD _ Set to inhibit recording of the file's modification and 
expiration dates. If not set, the file's expiration date can 
be modified, depending on the file retention parameters 
of the volume. 


FIB$V_SEQONLY Set to inform the file system that the file is to be 
processed sequentially only. 


FIB$B_WSIZE Controls the size of the file window used to map a disk 
file. The ACP uses the volume default if FIB$B_WSIZE is 
0. A value of 1 to 127 indicates the number of retrieval 
pointers to be allocated to the window. A value of -1 
indicates that the window should be as large as necessary 
to map the entire file. Note that the window is charged to 
the user's BYTELIM quota. 


FIB$W_FID Specifies the file identification of the file to be accessed. 


1.3.2.2 Operation 


The file is opened according to the access control specified (see Table 1-3). 


1.3.3 Extend 


The extend subfunction is used to allocate space to a disk file. This subfunction can be invoked using the 
major I/O functions IO$_CREATE and IO$_MODIFY (see Sections Section 1.6.1 and Section 1.6.4). The 
extend subfunction is performed if the bit FIB$V_EXTEND is set in the extend control word FIB$W_EXCTL. 
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Table 1-4 lists the FIB fields that control the processing of an extend subfunction. 


Table 1-4 


FIB Fields (Extend Control) 


Field Subfields 


Meaning 


FIB$W_EXCTL 


FIB$V_EXTEND 
FIB$V_NOHDREXT 


FIB$V_ALCON 


FIB$V_ALCONB 


FIB$V_FILCON 


FIB$V_ALDEF 


FIB$L_EXSZ 


FIB$L_EXVBN 


FIB$B_ALOPTS 


FIB$V_EXACT 


Extend control flags. The following flags are 
applicable to the extend subfunction: 


Set to enable extension. 


Set to inhibit generation of extension file 
headers. 


Allocates contiguous space. The extend 
operation fails if the necessary contiguous 
space is not available. 


Allocates the maximum amount of contiguous 
space. 


If both FIB$V_ALCON and FIB$V_ALCONB 
are set, a single contiguous area, whose size is 
the largest available but not greater than the 
size requested, is allocated. 


Marks the file as contiguous. This bit can only 
be set if the file does not have space already 
allocated to it. 


Allocates the extend size (FIB$L_EXSZ) or 
the system default, whichever is greater. 


Specifies the number of blocks to allocate to 
the file. 


The number of blocks actually allocated for 
this operation is returned in this longword. 
More blocks than requested can be allocated 
to meet cluster boundaries. 


Returns the starting virtual block number of 
the blocks allocated. FIB$L_EXVBN must 
initially contain 0 blocks. 


Contains option bits that control the 
placement of allocated blocks. The following 
bits are defined: 


Set to require exact placement; clear to specify 
approximate placement. If this bit is set and 
the specified blocks are not available, the 
extend operation fails. 
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Table 1-4 FIB Fields (Extend Control) (Continued) 
Field Subfields Meaning 


FIB$B_ALALIGN 


FIB$W_ALLOC 


FIB$V_ONCYL 


(zero) 


FIB$C_CYL 


FIB$C_LBN 


FIB$C_VBN 


FIB$C_RFI 


FIB$W_LOC_FID 
FIB$W_LOC_NUM 
FIB$W_LOC_SEQ 
FIB$B_LOC_RVN 
FIB$B_LOC_NMX 
FIB$L_LOC_ADDR 


Set to locate allocated space within a cylinder. 
This option functions correctly only when 
FIB$V_ALCON or FIB$V_ALCONB is 


specified. 


Contains the interpretation mode of the 
allocation (FIB$W_ALLOC) field. One of the 
following values can be specified: 


No placement data. The remainder of the 
allocation field is ignored. 


Location is specified as a byte relative volume 
number (RVN) in FIB$¢B_LOC_RVN anda 
cylinder number in FIB$L_LOC_ADDR. 


Location is specified as a byte RVN in 
FIB$B_LOC_RVN, followed by a longword 
logical block number (LBN) in 
FIB$L_LOC_ADDR. 


Location is specified as a longword virtual 
block number (VBN) of the file being extended 
in FIB$L_LOC_ADDR. A 0 VBN or one that 
fails to map indicates the end of the file. 


Location is specified as a three-word file ID in 
FIB$W_LOC_FID, followed by a longword 
VEN of that file in FIB$L_LOC_ADDR. A 0 
file ID indicates the file being extended. A 0 
VBN or one that fails to map indicates the end 
of that file. 


Contains the desired physical location of the 
blocks being allocated. Interpretation of the 
field is controlled by the FIB$B_ALALIGN 
field. The following subfields are defined: 


Three-word related file ID for RFI placement. 
Related file number. 

Related file sequence number. 

Related file RVN or placement RVN. 

Related file number extension. 


Placement LBN, cylinder, or VBN. 


34 


ACP-QIO Interface 
ACP Subfunctions 


1.3.3.2 Operation 


The specified number of blocks are allocated and appended to the file. The virtual block number assigned to 
the first block allocated is returned in FIB$L_EXVBN. The actual number of blocks allocated is returned in 
FIB$L_EXSZ. 


The actual number of blocks allocated is also returned in the second longword of the user's I/O status block. If 
a contiguous allocation (FIB$V_ALCON) fails, the size of the largest contiguous space available on the disk is 
returned in the second longword of the user's I/O status block. 


1.3.4 Truncate 


The truncate subfunction is used to remove space from a disk file. This subfunction can be invoked by the 
major I/O functions IO$_DEACCESS and IO$_MODIFY (see Sections Section 1.6.3 and Section 1.6.4). The 
truncate subfunction is performed if the bit FIB$V_TRUNC is set in the extend control word FIB$W_EXCTL. 
1.3.4.1 Input Parameters 


Table 1-5 lists the FIB fields that control the processing of a truncate subfunction. 


Table 1-5 FIB Fields (Truncate Control) 
Field Subfields Meaning 
FIB$W_EXCTL Extend control flags. The following flags are 
applicable to the truncate subfunction: 
FIB$V_TRUNC Must be set to enable truncation. 
FIB$V_MARKBAD Set to append the truncated blocks to the bad 


block file, instead of returning them to the 
free storage pool. Only one cluster can be 
deallocated. This is most easily accomplished 
by specifying the last VBN of the file in 
FIB$L_EXVBN. SYSPRV privilege or 
ownership of the volume is required to 
deallocate blocks to the bad block file. 


FIB$L_EXSZ Returns the actual number of blocks 
deallocated. FIB$L_EXSZ must initially 
contain a value of 0. 


FIB$L_EXVBN Specifies the first virtual block number to be 
removed from the file. The actual starting 
virtual block number of the truncate operation 
is returned in this field. 


1.3.4.2 Operation 


Blocks are deallocated from the file, starting with the virtual block specified in FIB$L_EXVBN and 
continuing through the end of the file. The actual number of blocks deallocated is returned in FIB$L_EXSZ. 
The virtual block number of the first block actually deallocated is returned in FIB$L_EXVBN. Because of 
cluster round-up, this value might be greater than the value specified. If FIB$V_MARKBAD is specified, the 
truncation VBN is rounded down instead of up, and the value returned in FIB$L_EXVBN might be less than 
that specified. 
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The number of blocks by which FIB$L_EXVBN was rounded up is returned in the second longword of the I/O 
status block. 


The truncate subfunction normally requires exclusive access to the file at run time. This means, for example, 
that a file cannot be truncated while multiple writers have access to it. 


An exception occurs when a truncate subfunction is requested for a write-accessed file that allows other 
readers. Although the truncate subfunction returns success status in this instance, the actual file truncation 
(the return of the truncated blocks to free storage) is deferred until the last reader deaccesses the file. If a new 
writer accesses the file after the truncate subfunction is requested, but before the last deaccess, the deferred 
truncation is ignored. 


Once the truncate operation has started, the file is locked from other writers for the duration of the truncate 
operation. Attempts to access the file for shared write access during this time will result in an 
SS$_ ACCONFLICT error. 


1.3.5 Read/Write Attributes 


The read and write attributes subfunctions are used for operations such as reading and writing file protection 
and creating and revising dates. A read or write attributes operation is invoked by specifying an attribute list 
with the QIO parameter P5. A read attributes operation can be invoked by the major I/O function 
IO$_ACCESS (see Section 1.6.2); a write attributes operation can be invoked by the major I/O functions 
IO0$_CREATE, I0$_DEACCESS, and IO$_MODIFY (see Sections Section 1.6.1, Section 1.6.3, and Section 
1.6.4). 


1.3.5.1 Input Parameters 


The read or write attributes subfunction is controlled by the attribute list specified by P5. The list consists of 
a variable number of two longword control blocks, terminated by a 0 longword, as shown in Figure 1-4. The 
maximum number of attribute control blocks in one list is 30. Table 1-6 describes the attribute control block 
fields. 


Figure 1-4 Attribute Control Block Format 


31 16 15 0 


ATR$W_TYPE ATR$W_SIZE 
ATR$L_ADDR 


(Additional Control Blocks) 


ZK0640GE 
Table 1-6 Attribute Control Block Fields 
Field Meaning 
ATR$W_SIZE Specifies the number of bytes of the attribute to be written, or the size of the buffer 


into which the attribute is to be read. Legal values for writing attributes are from 0 
to the maximum size of the particular attribute (see Table 1-7 on page 37), and legal 
values for the reading attributes are from 0 to the maximum unsigned 16-bit integer. 
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Table 1-6 Attribute Control Block Fields (Continued) 
Field Meaning 
ATR$W_TYPE Identifies the individual attribute to be read or written. 
ATR$L_ADDR Contains the buffer address of the memory space to or from which the attribute is to 


be transferred. The attribute buffer must be writable. 


Table 1-7 lists the valid attributes for ACP-QIO functions. The maximum size (in bytes) is determined by the 
required attribute configuration. For example, the Radix-50 file name (ATR$S_FILNAM) uses only 6 bytes, 
but it is always accompanied by the file type and file version, so a total of 10 bytes is required. Each attribute 
has two names: one for the code (for example, ATR$C_UCHAR) and one for the size (for example, 
ATR$S_UCHAR). 


Table 1-7 ACP-QIO Attributes 
ees N 1 Maximum Meanin 
ttribute Name Size (bytes) gs 

ATR$C_ACCDATE2 8 Corresponds to POSIX st_atime and reflects the last 
time a file was accessed. 

ATR$C_ACCESS_MODE 1 Access mode for following attribute descriptors. 

ATR$C_ACLEVEL? 4 5 6 1 File access level. 

ATR$C_ACLLENGTHS 7 4 Returns the size, in bytes, of the object's ACL. 

ATR$C ADDACLENT® 6 7 255 Adds an ACE to the beginning of the ACL when the 

~ ACE context value is 0; to the end of the ACL when the 

ACE context value is -1; or at a location pointed to by a 
prior ACL$¢C_FNDACETYP or ACL$C_FNDACLENT. 

ATR$C_ALCONTROL 14 Compatibility mode allocation data. 

ATR$C_ASCDATES3 9 35 Revision count (2 binary bytes), revision date, creation 
date, and expiration date, in ASCII. Format: 
DDMMMYY (revision date), HHMMSS (time), 
DDMMMYY (creation date), HHMMSS (time), 
DDMMMYY (expiration date). (The format contains no 
embedded spaces or commas.) 

ATR$C_ASCNAME 252 (ODS-5) File name, type, and version, in ASCII, including 

86 (ODS-2) punctuation. Format: name.type;version. 

Magnetic tape: contains 17-character file identifier 
(ANSI a); no version number. Overrides all other file 
name and file type specifications if supplied on input 
operations. If specified on an access operation and you 
want only a value to be returned, specify (in 
ATR$W_SIZE) a buffer of greater than 17 bytes. 
See Section 1.3.5.2 for additional information. 

ATR$C_ATTDATE2 8 Corresponds to POSIX st_ctime and reflects the last 


time a file attribute was modified. 
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Table 1-7 ACP-QIO Attributes (Continued) 
. 1 Maximum : 
Attribute Name Meaning 


Size (bytes) 


ATR$C_BACKLINK® 


ATR$C_BAKDATE* ® 10 6 
ATR$C_BLOCKSIZE 


ATR$C_BUFFER_OFFSET?® 


ATR$C_CREDATE 


ATR$C_DELACLENT® 6 7 


ATR$C_DELETE_ALL® 6 7 


ATR$C_DELETEACL3? 6 7 


ATR$C_DIRSEQ® 
ATR$C_ENDLBLAST 


ATR$C_EXPDAT®? 
ATR$C_EXPDATE? 


ATR$C_FILE_SPEC® 


ATR$C_FILNAM 


ATR$C_FILTYP 


ATR$C_FILVER 


ATR$C_FNDACLENT® ? 


ATR$C_FNDACETYP® 7 


ATR$C_FPRO? 4 


ATR$C_GRANT_ACE® 7 


38 


6 


8 


i) 


255 


7 
8 


4098 (ODS-5) 
512 (ODS-2) 
10 


File back link pointer. 
64-bit backup date and time. 


Magnetic tape block size. 


Offset length for ANSI magnetic tape header label 
buffer. 


64-bit creation date and time. 


Deletes an access control entry pointed to by the buffer 
address or, if the buffer address is 0, the ACE pointed to 
by a prior ACL$C_FNDACETYP or 
ACL$C_FNDACLENT. 


Delete the entire ACL, including protected entries. 


Deletes the entire ACL with the exception of protected 
ACEs. 


Directory update sequence count. 


End of magnetic tape label processing; provides AST 
control block. 


Expiration date in ASCII. Format: DDMMMYY. 
64-bit expiration date and time. 


Convert FID to file specification. See Section 1.3.5.2 for 
additional information. 


6-byte Radix-50 file name plus ATR$C_FILTYP and 
ATR$C_FILVER. See Section 1.3.5.2 for additional 
information. 


2-byte Radix-50 file type plus ATR$C_FILVER. See 
Section 1.3.5.2 for additional information. 


2-byte binary version number. See Section 1.3.5.2 for 
additional information. 


Locates an ACE pointed to by its buffer address. 


Locates an ACE of the type pointed to by its buffer 
address. 


File protection. 


Return an ACE that grants or denies access to the 
object. 
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Table 1-7 ACP-QIO Attributes (Continued) 
Attrib N Meena Meanin 
ttribute Name Size (bytes) 8 

ATR$C_HDR1_ACC 1 ANSI magnetic tape header label accessibility 
character. 

ATR$C_HEADER 512 Complete file header. This attribute is read only. 

ATR$C_HIGHWATER® 4 High-water mark (user read-only). 

ATR$C_JOURNAL® 1 Journal control flags. 

ATR$C_LINKCOUNT 2 Count of hardlinks. 

ATR$C_MATCHING. ACE!0® 255 ACE used to gain access (if any). This attribute can only 
be retrieved on the initial file access or create operation. 

ATR$C_MODACLENT® 6 7 255 Replaces the ACE pointed to by a prior 
ACL$C_FNDACETYP or ACL$C_FNDACLENT with 
the ACE pointed to by its buffer address. 

ATR$C_MODDATE2 8 Corresponds to POSIX st_mtime and reflects the last 
time data was modified. 

ATR$C_NEXT_ACE® 7 4 Advance to the next ACE in the ACL. 

ATR$C_PRIVS_USED® 4 Privileges used to gain access. This attribute can only 
be retrieved on the initial file access or create operation. 

ATR$C_READACE® 7 255 Reads the ACE pointed to by ACL$C_FNDACETYP or 
ACL$C_FNDACLENT into the buffer. 

ATR$C READACLS 7 512 Reads the entire ACL or as much as will fit in the 

~ supplied buffer. Only complete ACEs are transferred. 

ATR$C_RECATTR# 32 Record attribute area. Section 1.4 describes the record 
attribute area in detail. 

ATR$C_RESERVED!! 380 Modifies the reserve area. 

ATR$C_REVDATE®? 4 8 64-bit revision date and time. 

ATR$C_RPRO® 2 2-byte record protection. 

ATR$C_SEMASK® 8 File security mask and limit. 

ATR$C_STATBLK 32 Statistics block. This attribute is read only. Section 1.5 
describes the statistics block in detail. 

ATR$C_UCHAR? 9 4 4-byte file characteristics. (The file characteristics bits 
are listed following this table.) 

ATR$C_USERLABEL 80 User file label. This attribute is not supported for disk 
devices. 

ATR$C_UIC? 4 4-byte file owner UIC. 
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Table 1-7 ACP-QIO Attributes (Continued) 
Attrib N ‘ Mesa Meanin 
ttribute Name Size (bytes) s 
ATR$C_UIC_RO 4 4-byte file owner UIC. This attribute is read only. 


1. Attributes with an ATR$C_ prefix have two names: one with the ATR$C prefix for the code and 
one with an ATR$S_ prefix for the size, which is not included in the list. 
2. Not supported by all ACPs. Maintained on ODS-5 volumes when access dates are enabled using 
the DCL INITIALIZE or SET VOLUME commands. Not maintained on ODS-2 volumes. 
. Protected (can be written to only by system or owner). 
. Locked (cannot be written to while the file is locked). 
. For Files-11 C/D; returns 0. 
. Not supported for Files-11 On Disk Structure Level 1 or magnetic tapes. 
. The status from this attribute operation is returned in FIB$L_ACL_STATUS. 
. Exclusive access required. This operation does not complete successfully if other readers or 
writers are allowed. 
9. Not supported on writer operations to MTAACP; defaults are returned on read operations. 
10.Can be written only by the system, owner, or someone holding READALL privilege. 
11.The actual length available can decrease if the file is extended in a noncontiguous manner or if an 
ACL is applied to the file. 


COND Oe WH 


Table 1-8 lists the bits contained in the file characteristics longword, which is read with the ATR$C_UCHAR 


attribute. 
Table 1-8 File Characteristics Bits 


Bits 


Meaning 


FCH$M_NOBACKUP 
FCH$M_READCHECK 
FCH$M_WRITCHECK 
FCH$M_CONTIGB 
FCH$M_LOCKED 
FCH$M_CONTIG 
FCH$M_BADACL 
FCH$M_SPOOL 
FCH$M_DIRECTORY 
FCH$M_BADBLOCK 
FCH$M_MARKDEL 
FCH$M_ERASE 


FCH$M_ASSOCIATED! 


FCH$M_EXISTENCE! 
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Do not back up file. 

Verify all read operations. 

Verify all write operations. 

Keep file as contiguous as possible. 
File is deaccess-locked. 

File is contiguous. 

File's ACL is corrupt. 

File is an intermediate spool file. 
File is a directory. 

File contains bad blocks. 

File is marked for deletion. 

Erase file contents before deletion. 


File has an associated file. 


Suppress existence of file. 
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Table 1-8 File Characteristics Bits (Continued) 
Bits Meaning 
FCH$M_NOMOVE Disable movefile operations on this file. 
FCH$M_NOSHELVABLE File is not shelvable. 
FCH$M_SHELVED File is shelved. 


1. Files-11 C/D only. 


1.3.5.2 Attribute Descriptions 
This section contains descriptions of the following attribute codes that are listed in Table 1-7: 


e ATR$C_ASCNAME 
e ATR$C_FILE_SPEC 
e ATR$C_FILNAM 

e ATR$C_FILTYP 

e ATR$C_FILVER 
ATR$C_ASCNAME 


The ATR$C_ASCNAME attribute allows the file specification stored in a file's primary file header to be read 
and written. 


Reading the ATR$C_ASCNAME Attribute 


For ODS-5 volumes, the file specification is returned in the supplied buffer, and the name format is returned 
in the FIB$B_ASCNAME_FORMAT cell. 


The format in which the name is returned is controlled by the settings of the FIB$V_NAMES_8BIT and 
FIB$V_NAMES_16BIT flags in the same way as the output file specification parameter. A pseudoname can 
be returned in place of the actual file specification if the format is not one of those the calling program can 
accept. 


Unlike the output file specification parameter, the length of a file specification contained in the ASCNAME 
attribute is not passed back explicitly. To determine the length of the file specification, the calling program 
must search the attribute buffer for the first occurrence of the padding character. If neither the 
FIB$V_NAMES_8BIT nor the FIB$V_NAMES_16BIT flag is set, the buffer is padded with space (note that 
only ODS-2 format names are returned in this case). If one or more of the flags are set, the attribute buffer is 
padded with zeros. 


NOTE The file system does not enforce a minimum length on the attribute buffer. If the file 
specification is longer than the attribute buffer, the value returned is truncated without 
signaling an error or warning. 


In contrast, the file system does enforce a maximum size for the attribute buffer. Supplying a 
larger buffer returns a BADPARAM error. 


Writing the ATR$C_ASCNAME Attribute 


The ASCNAME attribute can only be written for files on ODS-2 or ODS-5 volumes provided that the 
FIB$V_NAMES_8BIT and FIB$V_NAMES_16BIT flags are clear. 
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The ability to write this attribute is only intended to provide compatibility with existing applications that do 
so. New and modified programs should not write this attribute. Changing its value can prevent a file from 
being permanently deleted. 


In those cases where it is legal to write the attribute, the contents of the attribute buffer (up to 252 bytes) are 
copied to the file name field in the file header. For ODS-5 headers, the format is set to ODS-2, and the file 
name length is set to the offset of the first space character. This can be 252 bytes or the length of the supplied 
buffer, whichever is the least. 


ATR$C_FILE_SPEC 
The FILE_SPEC attribute is a read-only attribute that returns the physical file specification in the form: 
DDnn: [DIR1.DIR2_DIRn]name.type; 1 


The file name returned is that from the file header, which may be different from that in the directory. The 
specification may be incomplete if any errors are encountered while reading the file headers of any of the 
directories in the path. 


For files on ODS-5 volumes, the path may contain file names that are in any of the three name formats. This 
creates a number of problems; for instance, the presence of periods in a directory name could return an 
ambiguous path specification. To avoid this and other problems, the file system makes use of services 
provided by RMS to translate the file specification and the components of the path to their escaped form. 


When you access files on an ODS-5 volume from a VAX system in a mixed architecture OpenVMS system, no 
escaped forms are returned. For an ODS-2 or ISO Latin-1 file format, the name stored in the file header is 
returned. For a UCS-2 file format, a pseudoname is returned, followed by the file identifier in parentheses. 
For example: 


DKA100: [ABC] \pUNICODE\.??? (10095,5,0) 


If the escaped form of the path is longer than can be accommodated by the buffer for the attribute, one or 
more directories in the path may be replaced by the DID of the rightmost of those replaced. This process is 
identical to that performed by RMS. 


However, if the file specification, even after DID abbreviation, is longer than can be accommodated by the 
buffer, the file name is truncated. The file specification string returned to the user buffer has a 2-byte count 
prefix. The count contains the number of bytes for the untruncated file specification. If the count is greater 
than the size of the user buffer (minus the two bytes that contain the count), the user can conclude that the 
returned file specification has been truncated. 


ATR$C_FILNAM, ATR$C_FILTYP, and ATR$C_FILVER 


The first two of these attributes allow the file name and file type to be read and written using Radix-50 
encoding. This encoding scheme enables 3 characters to be packed into a 16-bit word. Only 38 characters in 
the ODS-2 format set are valid for Radix-50 names, with the exceptions being dash (-) and underscore (_). 


The maximum component lengths of a Radix-50 encoded file specification are: 
e File name: 15 characters (10 bytes) 
e File type: 6 characters (4 bytes) 


As a result of the additional character and length restrictions, only a subset of legal ODS-2 file names is can 
be expressed in the Radix-50 encoding. 


The file system only attempts to read or write the three attributes if the format of the existing file name in 
the file header is ODS-2. If this is not the case, a NORAD50 error will be returned. If the existing file name is 
in ODS-2 format, but is incompatible with the Radix-50 encoding or the length limits on Radix-50 file names, 
a BADFILENAME error will be returned. 
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The ATR$C_FILVER attribute allows the file version number in the file header to be read or written as a 
2-byte integer. As the process requires the existing file name to be converted into a Radix-50 file name, the 
previous restriction also applies to this attribute. 


1.4 ACP-QIO Record Attributes Area 


Figure 1-5 shows the format of the record attributes area. 


Figure 1-5 ACP-QIO Record Attributes Area 
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FAT$W_DEFEXT FAT$W_MAXREC 
FAT$W_GBC 


(6 Bytes Reserved for Future Use) 


*“FAT$V_RTYPE Bits 0 - 3; FAT$V_FILEORG Bits 4 -7 


ZK-0641-Al 
Table 1-9 lists the record attributes values and their meanings. 
Table 1-9 ACP Record Attributes Values 
Field Value Meaning 
FAT$B TYPE Record type. Contains FAT$V_RTYPE and FAT$V_FILEORG. 
FAT$V_RTYPE Record type. The following bit values are defined: 
FAT$C_FIXED Fixed-length record 
FAT$C_VARIABLE Variable-length record 
FAT$C_VFC Variable-length record with fixed control 
FAT$C_UNDEFINED Undefined record format (stream binary) 
FAT$C_STREAM RMS stream format 
FAT$C_STREAMLF Stream terminated by LF 
FAT$C_STREAMCR Stream terminated by CR 
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Table 1-9 ACP Record Attributes Values (Continued) 


Field Value 
FAT$V_FILEORG 


FAT$B_RATTRIB 


FAT$W_RSIZE 


FAT$L_HIBLK? 


FAT$L_EFBLK? 4 


FAT$W_FFBYTE 

FAT$B_BKTSIZE 
FAT$B_VFCSIZE 

FAT$W_MAXREC 
FAT$W_DEFEXT 
FAT$W_GBC 


FAT$W_VERSIONS 


Meaning 


File organization. The following bit values are defined: 


FAT$C_DIRECT Direct file organization! 


FAT$C_INDEXED 
FAT$C_RELATIVE 
FAT$C_SEQUENTIAL 


Indexed file organization 
Relative file organization 
Sequential file organization 
Record attributes. The following bit values are defined: 
FAT$M_FORTRANCC 
FAT$M_IMPLIEDCC 
FAT$M_PRINTCC 
FAT$M_NOSPAN 


Fortran carriage control 
Implied carriage control 
Print file carriage control 


No spanned records 


FAT$M_MSBRCW2 Record count word (RCW) is MSB formatted 


Record size in bytes. 


Highest allocated VBN. The ACP maintains this field when the file is extended 
or truncated. Attempts to modify this field in a write attributes operation are 
ignored. 


FAT$W_HIBLKH 
FAT$W_HIBLKL 
End of file VBN 


High-order 16 bits 
Low-order 16 bits 


FAT$W_EFBLKH 
FAT$W_EFBLKL 
First free byte in FAT$L_EFBLK. 


High-order 16 bits 
Low-order 16 bits 


Bucket size, in blocks. 

Size in bytes of fixed-length control for VFC records. 
Maximum record size, in bytes. 

Default extend quantity. 

Global buffer count. 


Default version limit; valid only if the file is a directory 


1. Defined but not implemented. 
2. Variable-length record format (FAT$C_VARIABLE) only. 
3. Inverted format field. The high- and low-order 16 bits are transposed for compatibility with 


PDP-11 software. 
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4, When the end-of-file position corresponds to a block boundary; by convention, FAT$L_EFBLK 
contains the end-of-file VBN plus 1 and FAT$W_FFBYTE contains 0. 


1.5 ACP-QIO Attributes Statistics Block 


Figure 1-6 shows the format of the attributes statistics block. Table 1-10 lists the contents of this block. 


Figure 1-6 ACP-QIO Attributes Statistics Block 


31 


16 15 87 0 
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Table 1-10 Contents of the Statistics Block 


Field Subfields 


Meaning 


SBK$L_STLBN 


SBK$W_STLBNH 
SBK$W_STLBNL 
SBK$L_FILESIZE 


SBK$W_FILESIZH 
SBK$W_FILESIZL 


SBK$B_ACNT! 


Contains the starting LBN of the file if the file is 
contiguous. If the file is not contiguous, this field 
contains a value of 0. The LBN appears as an 
inverted longword (the high- and low-order 16 bits 
are transposed for PDP-11 compatibility). The 
following subfields are defined: 


Starting LBN (high-order 16 bits) 
Starting LBN (low-order 16 bits) 


Contains the size of the file in blocks. The file size 
appears as an inverted longword (the high- and 
low-order 16 bits are transposed for PDP-11 
compatibility). The following subfields are defined: 


File size (high-order 16 bits) 
File size (low-order 16 bits) 


Access count (low byte). Field is for PDP-11 
compatibility. 
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Table 1-10 Contents of the Statistics Block (Continued) 
Field Subfields Meaning 
SBK$B_LCNT! Lock count (low byte). Field is for PDP-11 
compatibility. 
SBK$L_FCB System pool address of the file's file control block. 
SBK$W ACNT! Access count (number of channels with file open 
7 currently). 
SBK$W_LCNT! Lock count (the number of access operations that 
have locked the file against writers). 
SBK$w_WCN! Writer count (the number of channels that currently 
have the file open for write). 
SBK$W_TCNT! Truncate lock count (the number of access operations 
that have locked the file against truncation). 
SBK$L_READS Number of read operations executed for the file on 
this channel. 
SBK$L_WRITES Number of write operations executed for the file on 


this channel. 


1. Accesses from processes on the local node in a cluster are counted. 


1.6 Major Functions 


The following sections describe the operation of the major ACP functions. Each section describes the required 
and optional parameters for a particular function, as well as the sequence in which the function is performed. 
For clarity, when a major function invokes a subfunction, the input parameters used by the subfunction are 
omitted. 


1.6.1 Create File 


Create file is a virtual I/O function that creates a directory entry or a file on a disk device, or a file on a 
magnetic tape device. 


The following is the function code: 

¢ IO$_CREATE 

The following are the function modifiers: 

¢ IO$M_CREATE—Creates a file. 

¢ IO$M_ACCESS—Opens the file on your channel. 

¢ JO$M_DELETE—Marks the file for deletion (applicable only to disk devices). 
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The following are the device- or function-dependent arguments for IO$_CREATE: 


e P1—The address of the file information block (FIB) descriptor. 


e P2—The address of the file name string descriptor (optional). 


e P3—The address of the word that is to receive the length of the resultant file name string (optional). 


e P4—The address of a descriptor for a buffer that is to receive the resultant file name string (optional). 


e P5—The address of a list of attribute descriptors (optional). 
Table 1-11 lists fields in the FIB that are applicable to the IO$_CREATE operation. 


Table 1-11 IO0$_CREATE and the FIB 


Field Subfields 


Meaning 


FIB$L_ACCTL 


FIB$V_REWIND 


FIB$V_CURPOS 


FIB$V_WRITETHRU 


FIB$W_CNTRLFUNC 


FIB$W_FID 


FIB$W_DID 


FIB$W_NMCTL 


FIB$V_NEWVER 


FIB$V_SUPERSEDE 


FIB$V_LOWVER 


Specifies field values that control access to the file. 
The following bits are applicable to the 
IO$_CREATE function: 


Set to rewind magnetic tape before creating the file. 
Any data currently on the tape is overwritten. 


Set to create magnetic tape file at the current tape 
position. (Note: a magnetic tape file is created at the 
end of the volume set if neither FIB$V_REWIND nor 
FIB$V_CURPOS is set.) If the tape is not positioned 
at the end of a file, FIB$V_CURPOS creates a file at 
the next file position. Any data currently on the tape 
past the current file position is overwritten. 


Specifies that the file header is to be written back to 
the disk. If not specified and the file is opened, 
writing of the file header can be deferred to some 
later time. 


Specifies the following value, which allows you to 
control actions subsequent to EOT detection on a 
magnetic tape file. 


Contains the file ID of the file created or entered. 
Contains the file identifier of the directory file. 


Controls the processing of the file name in a 
directory operation. The following bits are applicable 
to the IO$¢_ CREATE function: 


Set to create a file of the same name with the next 
higher version number. Only for disk devices. 


Set to supersede an existing file of the same name, 
type, and version. Only for disk devices. 


Set on return if a lower numbered version of the file 
exists. Only for disk devices. 
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Table 1-11 I10$_CREATE and the FIB (Continued) 
Field Subfields Meaning 
FIB$V_HIGHVER Set on return if a higher numbered version of the file 
exists. Only for disk devices. 
FIB$W_VERLIMIT Specifies the version limit for the directory entry 


created. Used only for disk devices and only when 
the first version of a new file is created. If 0, the 
directory default is used. If a directory operation was 
performed, FIB$W_VERLIMIT always contains the 
actual version limit of the file. 


FIB$L_ACL_STATUS Status of the requested ACL attribute operation, if 
any. The ACL attributes are included in Table 1-7. If 
no ACL attributes are given, SS$_ NORMAL is 
returned here. 


FIB$L_STATUS Access status. Programmers can control the security 
information being propagated as well as the source of 
this information by setting the following bits. 


1.6.1.2 Disk ACP Operation 


If the modifier IO$M_CREATE is specified, a file is created. The file ID of the file created is returned in 
FIB$W_FID. If the modifier IO$M_DELETE is specified, the file is marked for deletion. 


If a nonzero directory ID is specified in FIB$W_DID, a directory entry is created. The file name specified by 
parameter P2 is entered in the directory, together with the file ID in FIB$W_FID. (Table 1-2 describes the 
format for the file name string.) Wildcards are not permitted. Negative version numbers are treated as 
equivalent to a 0 version number. If a result string buffer and length are specified by P3 and P4, the actual 
file name entered, and its length, are returned. 


The version number of the file receives the following treatment: 


e Ifthe version number in the specified file name is 0 or negative, the directory entry created gets a version 
number one greater than the highest previously existing version of that file (or version 1 if the file did not 
previously exist). 


e Ifthe version number in the specified file name is a nonzero number and FIB$V_NEWVER is set, the 
directory entry created gets a version number one greater than the highest previously existing version of 
that file, or the specified version number, whichever is greater. 


e Ifthe version number in the specified file name is a nonzero number and the directory already contains a 
file of the same name, type, and version, the previously existing file is set aside for deletion if 
FIB$V_SUPERSEDE is specified. If FIB$V_SUPERSEDE is not specified, the create operation fails with 
a SS$_DUPFILNAM status. 


e If, after creating the new directory entry, the number of versions of the file exceeds the version limit, the 
lowest numbered version is set aside for deletion. 


e Ifthe file did not previously exist, the new directory entry is given a version limit as follows: the version 
limit is taken from FIB$W_VERLIMIT if it is a nonzero number; if it is 0, the version limit is taken from 
the default version limit of the directory file; if the default version limit of the directory file is 0, the 
version limit is set to 32,767 (the highest possible number). 
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The file name string entered in the directory is returned using the P3 and P4 result string parameters, if 
present. The file name string is also written into the header. If no directory operation was requested 
(FIB$W_DID is 0), the file name string specified by P2, if any, is written into the file header. 


If an attribute list is specified by P5, a write attributes subfunction is performed (see Section 1.3.5). 
If the modifier IO$M_ACCESS is specified, the file is opened (see Section 1.3.2). 


If the extend enable bit FIB$V_EXTEND is specified in the FIB, an extend subfunction is performed (see 
Section 1.3.3). 


Finally, if a file was set aside for deletion (IO$M_DELETE is specified), that file is deleted. If the file is 
deleted because the FIB$V_SUPERSEDE bit was set, the alternate success status SS$_ SUPERSEDE is 
returned in the I/O status block. If the file is deleted because the version limit was exceeded, the alternate 
success status SS$_ FILEPURGED is returned. 


If an error occurs in the operation of an IO$_CREATE function, all actions performed to that point are 
reversed (the file is neither created nor changed), and the error status is returned to the user in the I/O status 
block. 

1.6.1.3 Directory Entry Creation 


Creating a new version of a file eliminates default access to the previously highest version of the file. For 
example, creating RESUME.TXT;4 masks RESUME.TXT;3 so the DCL command TYPE RESUME. TXT yields 
the contents of version 4, not version 3. To protect the contents of the earlier version of a file, the creator of a 
file must have write access to the previous version of a file of the same name. 

1.6.1.4 Magnetic Tape ACP Operation 


No operation is performed unless the IO$M_CREATE modifier is specified. The magnetic tape is positioned as 
specified by FIB$V_REWIND and FIB$V_CURPOS, and the file is created. The name specified by the P2 
parameter is written into the file header label. 


If P5 specifies an attribute list, a write attributes subfunction is performed (see Section 1.3.5). 


If the modifier IO$M_ACCESS is specified, the file is opened (see Section 1.3.2). 


1.6.2 Access File 


This virtual I/O function searches a directory on a disk device or a magnetic tape for a specified file and 
accesses that file if found. 


The following is the function code: 

e I0$_ACCESS 

The following are the function modifiers: 

¢ IO$M_CREATE—Creates a file. 

¢ IO$M_ACCESS—Opens the file on your channel. 


1.6.2.1 Input Parameters 

The following are the device- or function-dependent arguments for IO$_ACCESS: 

e P1—The address of the file information block (FIB) descriptor. 

e P2—The address of the file name string descriptor (optional). 

e P3—The address of the word that is to receive the length of the resultant file name string (optional). 
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e P4—The address of a descriptor for a buffer that is to receive the resultant file name string (optional). 
e P5—The address of a list of attribute descriptors (optional). 
Table 1-12 lists FIB fields that are applicable to the IO$_ACCESS operation. 


Table 1-12 I0$_ACCESS and the File Information Block 
Field Subfields Meaning 
FIB$W_ Specifies the value that allows the user to control 
CNTRLFUNC ee eal to EOT detection on a magnetic 
FIB$W_VERLIMIT Receives the version limit for the file. Applicable only 


if FIB$W_DID is a nonzero number (if a directory 
lookup is done). Used only for disk devices. 


FIB$L_ACL_STATUS Status of the requested ACL attribute operation, if 
any. The ACL attributes are included in Table 1-7. If 
no ACL attributes are given, SS$_NORMAL is 
returned here. (For Files-11 C/D, this field is always 
set to SS$_ NORMAL.) 


FIB$L_STATUS Alternate access status. The following bits are 
supported: 


FIB$V_ALT_REQ Set to indicate whether the alternate access bit is 
required for the current operation. If not set, the 
alternate access bit is optional. 


FIB$V_ALT_GRANTED _ If FIB$V_ALT_REQ = 0 and the alternate access 
check succeeded, the FIB bit returned from the file 
system is set. 


FIB$L_ALT ACCESS A 32-bit mask that represents an access mask to 
check against file protection; for example, to open a 
file for read and to check whether it can be deleted. 
The mask has the same configuration as the standard 
protection mask. 


1.6.2.2 Operation 


If a nonzero directory file ID is specified in FIB$W_DID, a lookup subfunction is performed (see Section 1.3.1.) 
The version limit of the file found is returned in FIB$W_VERLIMIT. 


If the directory search fails with a “file not found” condition and the IO$M_CREATE function modifier is 
specified, the function is reexecuted as a CREATE. In that case, the argument interpretations for 
IO$_CREATE, rather than those for IO$_ACCESS, apply. 


If IO$M_ACCESS is specified, an access subfunction is performed to open the file (see Section 1.3.2). 


If P5 specifies an attribute list, a read attributes subfunction is performed (see Section 1.3.5). 


1.6.3 Deaccess File 


Deaccess file is a virtual I/O function that deaccesses a file and, if specified, writes final attributes in the file 
header. 
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The following is the function code: 


e I0O$_DEACCESS 
10$_DEACCESS takes no function modifiers. 


1.6.3.1 Input Parameters 

The following are the device- or function-dependent arguments for IO$_DEACCESS: 
e P1—The address of the file information block (FIB) descriptor. 

e P5—The address of a list of attribute descriptors (optional). 

The following FIB fields are applicable to the I0$_DEACCESS function: 


Field Meaning 


FIB$W_FID File ID of the file being deaccessed. This field can contain a value of 0. If it 
does not, it must match the file identifier of the accessed file. 


FIB$L_ACL_STATUS Status of the requested ACL attribute operation, if any. The ACL attributes 
are included in Table 1-7. If no ACL attributes are given, SS$_NORMAL is 
returned here. (For Files-11 C/D, this field is always set to SS$_NORMAL.) 


1.6.3.2 Operation 


For disk files, if P5 specifies an attribute control list and the file was accessed for a write operation, a write 
attributes subfunction is performed (see Section 1.3.5). If the file was opened for write, no attributes were 
specified, and FIB$V_DLOCK was set when the file was accessed, the deaccess lock bit is set in the file 
header, inhibiting further access to that file. 


For disk files, if the truncate enable bit FIB$V_TRUNC is specified in the FIB, a truncate subfunction is 
performed (see Section 1.3.4). 


Finally, the file is closed. Trailer labels are written for a magnetic tape file that was opened for write. 


1.6.4 Modify File 


Modify file is a virtual I/O function that modifies the file attributes or allocation of a disk file. The 
I0$_MODIFY function is not applicable to magnetic tape; that is, the function returns success, but no action 
is performed. 


The following is the function code: 
e IO$ MODIFY 
The following is the function modifier: 


¢ IO$M_MOVEFILE 


1.6.4.1 Input Parameters 
The following are the device- or function-dependent arguments for IO$_MODIFY: 
e P1—The address of the file information block (FIB) descriptor. 


e P2—The address of the file name string descriptor (optional). If specified, the directory is searched for the 
name. 


51 


ACP-QIO Interface 
Major Functions 


e P3—The address of the word that is to receive the length of the resultant file name string (optional). 
e P4—The address of a descriptor for a buffer that is to receive the resultant file name string (optional). 
e P5—The address of a list of attribute descriptors (optional). 

The following FIB fields are applicable to the IO$_MODIFY function: 


Field Subfields Meaning 


FIB$L_ACCTL Specifies field values that control access to the 
file. The following bit is applicable to the 
IO$ MODIFY function: 


FIB$V_WRITETHRU Specifies that the file header is to be written 
back to the disk. If not specified and the file is 
currently open, writing of the file header can be 
deferred to some later time. 


FIB$W_VERLIMIT If a nonzero number, specifies the version limit 
for the file. 
FIB$L_ACL_STATUS Status of the requested ACL attribute operation. 


The ACL attributes are listed in Table 1-7. If no 
ACL attributes are given, SS$_NORMAL is 
returned here. 


1.6.4.2 Operation 


If a nonzero directory ID is specified in FIB$W_DID, a lookup subfunction is executed (see Section 1.3.1). Ifa 
nonzero version limit is specified in FIB$W_VERLIMIT and the directory entry found is the latest version of 
that file, the version limit is set to the value specified. 


If P5 specifies an attribute list, a write attributes subfunction is performed (see Section 1.3.5). 


The file can be either extended or truncated. If FIB$V_EXTEND is specified in the FIB, an extend 
subfunction is performed (see Section 1.3.3). If FIB$V_TRUNC is specified in the FIB, a truncate subfunction 
is performed (see Section 1.3.4). Extend and truncate operations cannot be performed at the same time. 


1.6.5 Delete File 


Delete file is a virtual I/O function that removes a directory entry or file header from a disk volume. 
The following is the function code: 

¢ I0$_DELETE 

The following is the function modifier: 

e IO$M_DELETE—Deletes the file (or marks it for deletion). 

The following are the device- or function-dependent arguments for 10$_DELETE: 

e P1—The address of the file information block (FIB) descriptor. 

e P2—The address of the file name string descriptor (optional). 

e P3—The address of the word that is to receive the length of the resultant file name string (optional). 


e P4—The address of a descriptor for a buffer that is to receive the resultant file name string (optional). 
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The following FIB fields are applicable to the IO$_DELETE function: 


Field Subfields Meaning 


FIB$L_ACCTL Specifies field values that control access to the file. 
The following bits are applicable to the 
I0$_DELETE function: 


FIB$V_NOLOCK Allows the caller to mark a file for delete that is 

(Alpha only) currently open for write access. When the file is 
closed, it is automatically deleted. The file cannot be 
accessed by new callers after it has been marked for 
delete. 


FIB$V_WRITETHRU _ Specifies that the file header is to be written back to 
the disk. If not specified and the file is currently 
open, writing of the file header can be deferred to 
some later time. 


FIB$W_DID Contains the file identifier of the directory file. This 
field must be a nonzero number. 


FIB$W_FID Specifies the file identification to be deleted. 


1.6.5.1 Operation 


If a nonzero directory ID is specified in FIB$W_DID, a lookup subfunction is performed (see Section 1.3.1). 
The file name located is removed from the directory. 


If the function modifier IO$M_DELETE is specified, the file is marked for deletion. If the file is not currently 
open, it is deleted immediately. If the file is open, it is deleted when the last accessor closes it. 


1.6.6 Movefile Subfunction 
The movefile subfunction permits you to move the contents of a file, or part of the contents of a file, to a new 
disk location. This subfunction can, for example, form the basis of a disk defragmentation application. 


You can disable movefile operations on specific user files by specifying the /NOMOVE qualifier on the SET 
FILE command. Use the DIRECTORY/FULL and the DUMP/HEADER commands to find out if movefile 
operations are disabled on a file. 


1.6.6.1 Calling the Movefile Subfunction 


A program can invoke a movefile subfunction by issuing a QIO request using the function code IO$_MODIFY 
and the function modifier IO$M_MOVEFILE. This section describes the various input parameters that 
control the processing of movefile operations together with an operational description. 


1.6.6.1.1 Input Parameters Table 1-13 lists the FIB fields that control the processing of a movefile 
subfunction. 


Table 1-13 FIB Fields (Movefile) 
Field Subfields Meaning 
FIB$L_ACCTL Movefile control flag. The following flags are 


applicable: 
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Table 1-13 


FIB Fields (Movefile) (Continued) 


Field Subfields 


Meaning 


FIB$V_NOVERIFY 


FIB$V_CHANGE_VOL 


FIB$W_FID 


FIB$W_EXCTL 


FIB$V_ALCON 


FIB$V_ALCONB 


FIB$V_FILCON 
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Inhibits comparison of the moved blocks. If this flag 
is clear, the movefile operation verifies that the 
operation was carried out correctly by comparing 
the moved blocks to the original blocks. 


Enables the movefile operation to move blocks from 
one volume to another within a volume set. 


The movefile operation clears this flag if the 
specified file is a directory. 


Specifies the file identification of the file to be 
moved. 


Movefile control flags. The following flag applies to 
the movefile operation. All other FIB$W_EXCTL 
flags must be clear. 


Specifies that the movefile operation must allocate 
contiguous disk space to the moved blocks. If the 
necessary contiguous space is not available, the 
movefile operation fails. 


The movefile operation sets this flag if the file was 
previously marked as contiguous. 


Specifies that the movefile operation should attempt 
to allocate contiguous disk space to the moved 
blocks. That is, if the movefile operation cannot 
allocate contiguous space to all the moved blocks, it 
allocates contiguous space to as many of the blocks 
as possible. 


The movefile operation sets this flag if the file was 
previously marked as contiguous best try. 


Specifies that the entire file must be made 
contiguous. Do not set this flag without also setting 
the FIB$V_ALCON flag. 


If the FIB$V_FILCON flag is set, and either the 
FIB$V_ALCON flag is clear or the file would not be 
made contiguous by moving the specified virtual 
blocks, the movefile operation fails. 


The movefile operation sets this flag if the file was 
previously marked as contiguous. 
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Table 1-13 FIB Fields (Movefile) (Continued) 


Field 


Subfields 


Meaning 


FIB$B_ALOPTS 


FIB$B_ALALIGN 


FIB$W_ALLOC 


FIB$L_MOV_SVBN 


FIB$V_NOPLACE 


FIB$V_EXACT 


FIB$B_LOC_RVN 


FIB$L_LOC_ADDR 


Specifies that placement information will not be 
recorded in the file header. 


If this flag is clear and you specify exact placement 
for the moved blocks, placement information for 
those blocks will be recorded in the file header. If 
this flag is set, the placement information will not 
be recorded. 


You specify exact placement through the 
FIB$V_EXACT, FIB$C_LBN, and 
FIB$L_LOC_ADDR fields. 


Flags that control the placement of the allocated 
blocks. Currently, only the FIB$V_EXACT flag 
applies to the movefile operation. All other 
FIB$B_ALOPTS flags must be clear. The following 
flag is applicable: 


Set to require exact placement. If this flag is set and 
the specified blocks are not available, the movefile 
operation fails. 


Contains the interpretation mode of the allocation 
field (FIB$W_ALLOC). You can specify a field value 
of 0 or you can specify the symbolic value 
FIB$C_LBN. If you specify 0, the allocation field is 
ignored. 


Contains the desired location of the blocks being 
allocated. Interpretation of the field is controlled by 
the FIB$B_ALALIGN field. The following subfields 
are defined: 


Specifies the relative volume number (RVN) of the 
volume to which the blocks are moved. Do not 
specify a value for this field unless you have set the 
FIB$V_CHANGE_VOL flag. 


If the FIB$C_LBN and FIB$V_EXACT flags are set, 
specifies the starting logical address to which the 
blocks are moved. 


Specifies the virtual block number (VBN) of the first 
block to be moved. 


The starting VBN must correspond to the first block 
of a disk cluster. The value must be greater than 0 
and it must not exceed the number of virtual blocks 
allocated to the file. If you specify an invalid value, 
the movefile operation fails. 
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Table 1-13 FIB Fields (Movefile) (Continued) 


Field Subfields Meaning 


FIB$L_MOV_VBNCNT Specifies the number of consecutive virtual blocks to 
be moved. 


This value must be a multiple of the disk cluster 
size, and it must not exceed the difference between 
the greatest VBN allocated to the file and the 
FIB$L_MOV_SVBN value. If you specify a value of 
0, the movefile operation moves all the virtual 
blocks between the FIB$L_MOV_SVBN value and 
the greatest VBN. 


If you specify an invalid value, the movefile 
operation fails. 


Operation 


A program can perform a movefile operation on a file if the following conditions are met: 
e ©The program has write and control access to the file. 

e = The file is closed. 

¢ Movefile operations are not disabled on the file. 


Movefile operations are automatically disabled on critical system files. You can disable movefile operations on specific 
user files by specifying the /NOMOVE qualifier with the SET FILE command. 


e =6The operation is not interrupted. 


If the movefile operation is interrupted by any other operation, such as a read or write operation, the movefile 
operation aborts and the file remains in its original position. 


The movefile operation moves a specified number of consecutive virtual blocks to new logical blocks on disk, beginning 
with the virtual block specified in the FIB$L_SVBN field. 


The number of blocks moved is specified in the FIB$L_VBNCNT field. To move an entire file, specify FIB$L_VBNCNT as 
0 and FIB$L_SVBN as 1. 


To specify a starting logical block for the moved blocks, specify the logical block address in the FIB$L_LOC_ADDR 
subfield and set the FIB$C_LBN and the FIB$V_EXACT flags. 


To move the blocks to another volume, or move blocks that span more than one volume, set the FIB$V_CHANGE_VOL 
flag of the FIB$L_ACCTL field. Use the FIB$B_LOC_RVN subfield of the FIB$W_ALLOC field to specify the volume to 
which the blocks are moved. If you do not specify a volume, the blocks are moved to the volume containing the first virtual 
block. Note that you cannot move blocks of a directory file to another volume. 


If the file was previously marked as contiguous, the movefile operation sets the FIB$V_ALCON, FIB$V_ALCONB, and 
FIB$V_FILCON flags. This ensures that a contiguous file is not fragmented by a movefile operation. 


For virtual blocks beyond the file's highwater mark, the movefile operation allocates new logical blocks but does not copy 
the contents. The position of the file's highwater mark remains unchanged. 


1.6.7 Mount 


On VAX, Alpha, and I64 systems, mount is a virtual I/O function that informs the ACP when a disk or 
magnetic tape volume is mounted. MOUNT privilege is required. 
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I0$_MOUNT takes no arguments or function modifiers. This function is part of the volume mounting 
operation only, and it is not meant for general use. Most of the actual processing is performed by the MOUNT 
command or the Mount Volume (SMOUNT) system service. 


1.6.8 


ACP Control 


ACP Control is a virtual I/O function that performs ancillary control functions, depending on the arguments 


s 


pecified. 


The following is the function code: 


I0$_ACPCONTROL 


The following is the function modifier: 


1 


IO$M_DMOUNT—Dismounts a volume. 


6.8.1 Input Parameters 


The following are the device- or function-dependent arguments for IO$_ACPCONTROL: 


Table 1-14 


P1—tThe address of the file information block (FIB) descriptor. 


P2—The address of the file name string descriptor (optional). 


P3—The address of the word that is to receive the length of the resultant file name string (optional). 


P4—The address of a descriptor for a buffer that is to receive the resultant file name string (optional). 


Table 1-14 lists FIB fields that control the processing of the IO$_ACPCONTROL function. 


10$_ ACPCONTROL and the FIB 


Field Subfields 


Meaning 


FIB$W_CNTRLFUNC 


FIB$L_CNTRLVAL! 


FIB$L_ACL_STATUS 


FIB$L_STATUS! 


FIB$V_ALT_REQ 


FIB$V_ALT_GRANTED 


Specifies the control function to be performed. 
This field overlays FIB$W_EXCTL. 


Specifies additional function-dependent data. This 
field overlays FIB$L_EXSZ. 


Status of the requested ACL attribute operation, if 
any. The ACL attributes are included in Table 1-7. 
If no ACL attributes are given, SS$_NORMAL is 
returned here. For Files-11 C/D, this field is 
always set to SS$_NORMAL. 


Alternate access status. The following bits are 
supported: 


Set to indicate whether the alternate access bit is 
required for the current operation. If not set, the 
alternate access bit is optional. 


If FIB$V_ALT_REQ = 0 and the alternate access 
check succeeded, the FIB bit returned from the file 
system is set. 
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Table 1-14 10$_ACPCONTROL and the FIB (Continued) 
Field Subfields Meaning 
FIB$L_ALT_ ACCESS! A 32-bit mask that represents an access mask to 


check against file protection; for example, to open 
a file for read and to check whether it can be 
deleted or not. The mask has the same 
configuration as the standard protection mask. 


1. Not supported or valid for Files-11 C/D. 


1.6.8.2 Magnetic Tape Control Functions 
Table 1-15 lists the FIB field applicable to magnetic tape operations. 


Table 1-15 Magnetic Tape Operations and the FIB 
Field Subfields Meaning 
FIB$W_CNTRLFUNC Several ACP control functions are used for magnetic 


tape positioning. These functions are specified by 
supplying a FIB with P1 containing the FIB descriptor 
address. Modifiers and parameters P2, P3, and P4 are 
not allowed. These functions clear serious exceptions in 
magnetic tape drivers. The following control functions 
can be specified to control magnetic tape positioning: 


FIB$C_REWINDFIL Rewind to beginning-of-file. 
FIB$C_REWINDVOL Rewind to beginning-of-volume set. 


FIB$C_POSEND Position to end-of-volume set. 
FIB$C_NEXTVOL Force next volume. 
FIB$C_SPACE Space n blocks forward or backward. The 


FIB$L_CNTRLVAL field specifies the number of 
magnetic tape blocks to space forward if positive or to 
space backward if negative. 


FIB$C_CLSEREXCP _Ifset, clears the serious exception in the magnetic tape 
driver (see FIB$C_USEREOT in Section 1.6.1 and 
Section 1.6.2). If writing, allows you to write data 
blocks beyond the EOT marker, which can result in the 
magnetic tape not conforming to the ANSI standard for 
magnetic tapes (see ANSI Standard X3.27-1978). If 
reading, allows you to handle the move to the next 
volume or to stop reading the tape. Do not attempt to 
read past EOV. 
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1.6.8.3 Miscellaneous Disk Control Functions 


Several ACP control functions are available for disk volume control. The following function does not use 
parameters P2, P3, and P4: 


IO$M_DMOUNT Specifying the dismount modifier on the IO$_ACPCNTRL function executes 
a dismount QIO. No parameters in the FIB are used; the FIB can be 
omitted. This function does not perform a dismount by itself, but is used to 
synchronize the ACP with the DISMOUNT command and the Dismount 
Volume ($DISMOUNT) system service. 


The FIB$W_CNTRLFUNC field of the FIB specifies the following miscellaneous control functions (with no 
modifier on the IO$_ACPCONTROL function code). These functions use no other parameters. 


FIB$C_REMAP Remap a file. The file window for the file open on the user's channel is 
remapped so that it maps the entire file. 


FIB$C_LOCK_VOL Allocation lock the volume. Operations that change the file structure, such 
as file creation, deletion, extension, and deaccess, are not permitted. If such 
requests are queued to the file system for an allocation-locked volume, they 
are not processed until the FIB$C_UNLK_VOL function is issued to unlock 
the volume. 


To issue the FIB$¢C_LOCK_VOL function, you must have either a system 
UIC or SYSPRYV privilege, or be the owner of the volume. 


FIB$C_UNLK_VOL Unlock the volume. Cancels FIB$C_LOCK_VOL. To issue this function, you 
must have either a system UIC or SYSPRV privilege, or be the owner of the 
volume. 


1.6.8.4 Disk Quotas 


Disk quota enforcement is enabled by a quota file on the volume, or relative volume 1 if the file is on a volume 
set. The quota file appears in the volume's master file directory (MFD) under the name QUOTA.SYS;1. This 
section describes the control functions that operate on the quota file. 


Table 1-16 lists the enable and disable quota control functions. 


Table 1-16 Disk Quota Functions (Enable/Disable) 
Value Meaning 
FIB$C_ENA_QUOTA Enable the disk quota file. If a nonzero directory file ID is specified in 


FIB$W_DID, a lookup subfunction is performed to locate the quota file (see 
Section 1.3.1). To issue this function, you must have either a system UIC or 
SYSPRV privilege, or be the owner of the volume. 


The quota file specified by FIB$W_FID, if present, is accessed by the ACP, 
and quota enforcement is turned on. By convention, the quota file is named 
[0,0] QUOTA.SYS;1. Therefore, FIB$W_DID should contain the value 4,4,0 
and the name string specified with P2 should be “QUOTA.SYS;1”. 


FIB$C_DSA_QUOTA Disable the disk quota file. The quota file is deaccessed and quota 
enforcement is turned off. To issue this function, you must have either a 
system UIC or SYSPRV privilege, or be the owner of the volume. 
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Table 1-17 lists the quota control functions that operate on individual entries in the quota file. Each operation 
transfers quota file data to and from the ACP using a quota data block. This block has the same format as a 
record in the quota file. Figure 1-7 shows the format of this block. 


Table 1-17 Disk Quota Functions (Individual Entries) 


Value Meaning 


FIB$C_ADD_QUOTA Add an entry to the disk quota file, using the UIC and quota specified in the 
P2 argument block. FIB$C_ADD_QUOTA requires write access to the quota 
file. 


FIB$C_EXA_QUOTA Examine a disk quota file entry. The entry whose UIC is specified in the P2 
argument block is returned in the P4 argument block, and its length is 
returned in the P38 argument word. Using two flags in FIB$L_CNTRLVAL, it 
is possible to search through the quota file using wildcards. The two flags 


are: 
FIB$V_ALL_MEM Match all UIC members 
FIB$V_ALL_GRP Match all UIC groups 


The ACP maintains position context in FIB$L_WCC. On the first examine 
call, you specify 0 in FIB$L_WCC; the ACP returns a nonzero value so that 
each succeeding examine call returns the next matching entry. 


Read access to the quota file is required to examine all nonuser entries. 


FIB$C_MOD_QUOTA Modify a disk quota file entry. The quota file entry specified by the UIC in the 
P2 argument block is modified according to the values in the block, as 
controlled by the following three flags in FIB$L_CNTRLVAL: 


FIB$V_MOD_PERM Change the permanent quota 
FIB$V_MOD_OVER Change the overdraft quota 
FIB$V_MOD_USE Change the usage data 


The usage data can be changed only if the volume is locked by 
FIB$C_LOCK_VOL (see Section 1.6.8.3). FIB$C_MOD_QUOTA requires 
write access to the quota file. 


The P3 and P4 arguments return the modified quota entry to you. 


By using the flags FIB$V_ALL_MEM and FIB$V_ALL_GRP, you can search 
through the quota file using wildcards just as you would with the 
FIB$C_EXA_QUOTA function. 


FIB$C_REM_QUOTA Remove a disk quota file entry whose UIC is specified in the P2 argument 
block. FIB$C_REM_QUOTA requires write access to the quota file. 


The P3 and P4 arguments return the removed quota file entry to you. 


By using the flags FIB$V_ALL_MEM and FIB$V_ALL_GRP, you can search 
through the quota file using wildcards just as you would with the 
FIB$C_EXAQUOTA function. 
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Figure 1-7 Quota File Transfer Block 
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I0$_ACPCONTROL functions that transfer quota file data between the caller and the ACP use the following 
device- or function-dependent arguments: 


e P2—The address of a descriptor for the quota data block being sent to the ACP. 
e P3—The address of a word that returns the data length. 
e P4—The address of a descriptor for a buffer to receive the quota data block returned from the ACP. 


1.7 VO Status Block 


Figure 1-8 shows the I/O status block (IOSB) for ACP--QIO functions. Appendix A lists the status returns for 
these functions. (The OpenVMS system messages documentation provides explanations and suggested user 
actions for these returns.) 


The file ACP returns a completion status in the first longword of the IOSB. In an extend operation, the second 
longword is used to return the number of blocks allocated to the file. If a contiguous extend operation 
(FIB$V_ALCON) fails, the second longword is used to return the size of the file after truncation. 


Values returned in the IOSB are most useful during operations in compatibility mode. When executing 
programs in the native mode, use the values returned in FIB locations. 


Figure 1-8 IOSB Contents — ACP-QIO Functions 
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If an extend operation (including CREATE) was performed, IOSB+4 contains the number of blocks allocated, 
or the largest available contiguous space if a contiguous extend operation failed. If a truncate operation was 
performed, IOSB+4 contains the number of blocks added to the file size to reach the next cluster boundary. 
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2. Disk Drivers 


This chapter describes the use of disk drivers that support the disk devices listed in the Software Product 
Description for the OpenVMS Operating System (SPD 82.35.xx). The chapter also includes descriptions of 
many of the supported disks and controllers; however, not all supported devices are described here. Refer to 
the Software Product Description for the OpenVMS Operating System for the definitive list of supported 
devices.) 


All disk drivers support Files-11 On-Disk Structure Level 1 and Level 2 file structures. Access to these file 
structures is through the DCL commands INITIALIZE and MOUNT, followed by the RMS calls described in 
the OpenVMS Record Management Utilities Reference Manual. Files in RT-11 format can be read or written 
with the file exchange facility EXCHANGE. 


2.1 Supported Disk Devices and Controllers 


The following sections provide descriptions of disk devices. 


To obtain more information about a device, use the DCL command SHOW DEVICE with the /FULL qualifier, 
the Get Device/Volume Information ($GETDVI) system service (from a program), or the FS{GETDVI lexical 
function (in a command line or command procedure). Section 2.3 lists the information on disk devices 
returned by $GETDVI. 


2.1.1 UDA50 UNIBUS Disk Adapter 


The UDA50 UNIBUS Disk Adapter is a microprocessor-based disk controller for mass storage devices that 
implements the DIGITAL Storage Architecture (DSA); for more information on the DSA, see Section 2.2.3. 


The UDAS5O controller is used to connect any combination of four RA60, RA80, and RA81 disk drives to the 
UNIBUS. Two UDA50 controllers can be attached to a single UNIBUS for a maximum of eight disk drives per 
UNIBUS. On the VAX-11/780 processor, the operating system supports one UDA5O on the first UNIBUS, 
which can accommodate certain other options. Adding a second UDA50 requires a second UNIBUS. With the 
exception of the first UNIBUS, a maximum of two UDA50 controllers per UNIBUS are supported. If two 
UDAS0 controllers are on a UNIBUS, no other options can be placed on that UNIBUS. The VAX-11/730 
processor supports only one UDA50 per UNIBUS. 


The UDASO, in implementing DSA, takes over the control of the physical disk unit. The operating system 
processes request virtual or logical I/O on disks controlled by the UDA50. The operating system maps virtual 
block addresses into logical block addresses. The UDA50 then resolves logical block addresses into physical 
block addresses on the disk. 


The UDA50 controller corrects bad blocks on the disk by requesting that the disk class driver revector a 

failing physical block to another, error-free physical block on the disk; the logical block number is not changed 
(see Section 2.2.11.1). Any bad blocks that might exist on a disk attached to a UDA50 are transparent to the 
operating system, which does logical or virtual I/O to such a disk. The UDA50 also corrects most data errors. 
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2.1.2 KDA50 Disk Controller 


The KDAS0 disk controller is a two-module disk controller that allows the RA-series DSA disk drives to be 
attached to Q-bus systems. The KDA50 performs the same functions as the UDA50 (see Section 2.1.1). 


2.1.3 KDB50 Disk Controller 


The KDB50 disk controller is a two-module disk controller that allows the RA-series DSA disk drives to be 
attached to BI bus systems, such as the VAX 8200 processor. The KDB50 performs the same functions as the 
UDAS0 (see Section 2.1.1). 


2.1.4 HSC40, HSC50, and HSC70 Controllers 


HSC controllers are high-speed, high-availability controllers for mass storage devices that implement the 
DIGITAL Storage Architecture (DSA); for more information about the DSA, see Section 2.2.3. An HSC 
controller is connected to a processor by a Computer Interconnect (CI) bus. The operating system supports the 
use of the HSC controllers in controlling the RA family of disks. 


The HSC40 can support up to 12 SDI (standard disk interface) disks from the SA or RA families of disk drives 
or a combination of up to 12 SDI disk drives and TA-series tape drives. 


The HSC70 can support up to 32 SDI disks from the SA or RA families of disk drives or a combination of SDI 
disk drives and TA-series tape drives. 


HSC controllers, in implementing DSA, take over the control of the physical disk unit. System processes 
request virtual or logical I/O on disks controlled by the HSC controller. The operating system maps virtual 
block addresses into logical block addresses. The HSC controller then resolves logical block addresses into 
physical block addresses on the disk. 


HSC controllers correct bad blocks on the disk by revectoring a failing physical block to another, error-free 
physical block on the disk; the logical block number is not changed. The operating system, which performs 
logical or virtual I/O to such a disk, does not recognize that any bad blocks might exist on a disk attached to 
an HSC controller. HSC controllers also correct most data errors. 


The HSC series of controllers provides access to disks despite most hardware failures. Use of an HSC 
controller permits two or more processors to access files on the same disk. 


NOTE Only one system should have write access to a Files-11 On-Disk Structure Level 1 disk or toa 
foreign-mounted disk; all other systems should only have read access to the disk. For Files-11 
On-Disk Structure Level 2 volumes, the operating system enables read/write access to all nodes 
that are members of the same cluster. 


HSC-series controllers allow you to add or subtract disks from the device configuration without rebooting the 
system. 


2.1.5 SII Integral Adapter 


The SII integral adapter on the MicroVAX 3300/3400 processor provides access through the DIGITAL Storage 
Systems Interconnect (DSSI) bus to a maximum of seven storage devices. 


The term dual-host refers to pairs of CPUs connected to a bus. In dual-host configurations of MicroVAX 
3300/3400 CPUs, the DSSI bus must be connected between the SII integral adapters present on both CPUs. 


A maximum of six devices can be connected to the EDA640 adapter, which is implemeneted by the SII chip, 
DXX chip, and 128K RAM chip, in dual-host configurations. 
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2.1.6 KFQSA Adapter 


The KFQSA adapter allows a maximum of seven storage devices for use on Q-bus systems. 


In dual-host configurations of MicroVAX 3800/3900 CPUs, the DSSI bus must be connected between KFQSA 
adapters present on both CPUs. 


A maximum of six devices can be connected to the KFQSA adapter in dual-host configurations. 


2.1.7 RQDX3 Disk Controller 


The RQDX83 controller is a Q-bus controller used with the RD series of Winchester-type disk drives and the 
RX33 and RX50 flexible diskette drives. 


2.1.8 RA70 and RA90 Disk Drives 


The RA70 is a 5.25-inch, 280-MB high-performance DSA disk drive that uses thin-film media. It has an 
average access time of 27.0 ms and average seek time of 19.5 ms. The RA70 uses the Standard Disk Interface 
(SDD and the KDA50 controller, and can be dual-ported. 


The RAQ0 is a 1.2 GB disk drive designed with thin-film heads and 9-inch thin-film media with an average 
seek time of 18.5 ms. The RA90 conforms to DSA and uses the SDI. Both the RA70 and RA90 disk drives can 
be connected to medium-sized systems with the HSC-series controllers, KDB50, or UDA50 controllers. 


2.1.9 RA60 Disk 


The RA60 device uses high-capacity, removable media that provides 205 MB of usable storage (7.5 million bits 
of data per square inch) with transfer rates of 1.9 MB per second (burst) and 950 Kb per second (sustained). 
The RA60 belongs to the DIGITAL Storage Architecture (DSA) family of disk devices (see Section 2.2.3). It is 
connected to either a UNIBUS Disk Adapter (UDA50) or an HSC50 controller. Up to four disk drives can be 
connected to each UDA5O. Up to 24 disk drives can be connected to each HSC50. 


2.1.10 RA80/RB80/RM80 and RA81 Fixed-Media Disks 


The R80 disk drive is a high-capacity, moving-head disk whose nonremovable media consists of 14 data 
surfaces. Depending on how it is connected to the system, the R80 is identified internally as an RA80, RB80, 
or RM80, as follows: 


e RA80—An R80 connected to the system through a UNIBUS disk adapter (UDA50) or an HSC50 
controller. Up to four disk drives can be connected to each UDA5O. Up to 24 disk drives can be connected 
to each HSC50. 


e RB80—On VAX systems, an R80 connected to the system through an RB730 controller on a VAX-11/730 
processor. Of the maximum of four drives that can be connected to an RB730 controller, only one can be an 
RB80. 


e RM80—On VAX and Alpha systems, an R80 connected to the system through a MASSBUS adapter 
(MBA). Up to eight disk drives can be connected to each MBA. 


The RA81 is a high-capacity disk drive with nonremovable media that can hold more than 890,000 blocks of 
data. This translates into more than 455 MB per spindle. The RA81 is connected to a UDA50 or an HSC50 
controller. Up to four disk drives can be connected to each UDA5O. Up to 24 drives can be connected to each 
HSC50. 


The RA80 and RA81 belong to the DIGITAL Storage Architecture (DSA) family of disk devices (see Section 
2.2.3). 
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2.1.11 RB0O2 and RLO2 Cartridge Disk (VAX Only) 


On VAX systems, the RLO2 cartridge disk is a removable, random-access mass storage device with two data 
surfaces. The RL02 is connected to the system by an RL11 controller that interfaces with the UNIBUS 
adapter. Up to four RLO2 disk drives can be connected to each RL11 controller. For physical I/O transfers, the 
track, sector, and cylinder parameters describe a physical 256-byte RLO2 sector (see Section 2.4). 


When the RLO2 is connected to an RB730 controller on a VAX-11/730 processor, it is identified internally as 
an RBO2 disk drive. Disk geometry is unchanged and RLO2 disk packs can be exchanged between drives on 
different controllers. Up to four drives can be connected to the RB730 controller. 


2.1.12 RC25 Disk (VAX Only) 


On VAX systems, the RC25 disk is a self-contained, Winchester-type, mass storage device that consists of a 
disk adapter module, a disk drive, and an integrated disk controller. The drive contains two 8-inch, 
double-sided disks. One of the disks (RCF25) is a sealed, nonremovable, fixed-media disk. The other disk is a 
removable cartridge disk that is sealed until it is loaded into the disk drive. The disks share a common drive 
spindle, and together they provide 52 million bytes of storage. Adapter modules interface the RC25 with 
either a UNIBUS system or a Q-bus system. 


2.1.13 RD53 and RD54 Disks (VAX Only) 


On VAX systems, the RD53 and RD54 are 5.25-inch, full-height, Winchester-type drives with average access 
time of 38 ms and a data transfer rate of 0.625 MB per second. The RD53 and RD54 have a formatted capacity 
of 71 MB and 159 MB, respectively. When used with the RQDX3 controller, the RD53 and RD54 are DSA 
disks. 


See Section 2.2.12 for information about using RD series disks on the VAXstation 2000. 


2.1.14 RF3O and RF71 Disks 


The RF30 is a 150-MB, 5.25-inch, half-height disk drive while the RF71 is a 400-MB, full-height disk drive. 
The RF30 and RF71 include an embedded controller for multihost access and a mass storage control protocol 
(MSCP) server. The RF71 has a peak data transfer rate of 1.5 MB per second with average seek and access 
time of 21 ms and 29 ms, respectively. 


Both the RF30 and RF71 disks use DIGITAL Storage System Interconnect (DSSI) bus and host adapters. 


2.1.15 RK06 and RKO7 Cartridge Disks (VAX Only) 


On VAX systems, the RK06 cartridge disk is a removable, random-access, bulk storage device with three data 
surfaces. The RKO7 cartridge disk is a double-density RK06. The RK06 and RKO7 are connected to the system 
by an RK611 controller that interfaces to the UNIBUS adapter. Up to eight disk drives can be connected to 
each RK611. 


2.1.16 RM03 and RM05 Pack Disks (VAX Only) 


On VAX systems, the RM03 and RM05 pack disks are removable, moving-head disks that consist of five data 
surfaces for the RM03 and 19 data surfaces for the RM05. These disks are connected to the system by a 
MASSBUS adapter (MBA). Up to eight disk drives can be connected to each MBA. 
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2.1.17 RPO5 and RP0O6 Disk (VAX Only) 


On VAX systems, the RP05 and RP06 removable disks consist of 19 data surfaces and a moving read/write 
head. The RP06 removable disk has approximately twice the capacity of the RP05. These disks are connected 
to the system by an MBA. Up to eight disk drives can be connected to each MBA. 


2.1.18 RPO07 Fixed-Media Disk (VAX Only) 


On VAX systems, the RP07 is a 516-MB, fixed-media disk drive that attaches to the MASSBUS of the 
VAX-11/780 system. The RPO7 transfers data at 1.3 million bytes per second or as an option at a peak rate of 
2.2 million bytes per second. The nine platters rotate at 3600 rpm and their data is accessed at an average 
speed of 31.3 ms. These disks are connected to the system by an MBA. Up to eight disk drives can be 
connected to each MBA. 


2.1.19 RRD40 and RRD50 Read-Only Memory (CD-ROM) 


The RRD40 and RRD50 are compact disc read-only memory (CD-ROM) devices that use replicated media 
with a formatted capacity of approximately 600 MB. 


The RRD4O0 is a 5.25-inch half-height, front-loading tabletop or embedded device that attaches to the system 
using either the Small Computer System Interface (SCSI) or Q-bus interface. 


The RRD50 is a 5.25-inch, top-loading tabletop device that attaches to the system using a Q-bus interface. 


The RRD40 has an average access time of 0.5 second while the average access time for the RRD50 is 1.5 
seconds. Both the RRD40 and RRD50 have a data transfer rate of 150 KB per second. 


The media for the RRD40 and the RRD50 are removable 4.7-inch (120-mm) compact discs. However, the 
media for the RRD40 are enclosed in protective self-loading carriers. The RRD40 with a SCSI interface is also 
available as an embedded unit. The RRD40 and RRD50 Q-bus subsystems are standard disk MSCP devices. 


2.1.20 RX01 Console Disk (VAX Only) 


On VAX systems, the RX01 disk uses a diskette. The disk is connected to the LSI console on the VAX-11/780, 
which the driver accesses using the MTPR and MFPR privileged instructions. 


For logical and virtual block I/O operations, data is accessed with one block resolution (four sectors). The 
sector numbers are interleaved to expedite data transfers. Section 2.2.10 describes sector interleaving in 
greater detail. 
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For physical block I/O operations, the track, sector, and cylinder parameters describe a physical, 128-byte 
RX01 sector (see Figure 2-1 and Section 2.4). Note that the driver does not apply track-to-track skew, cylinder 
offset, or sector interleaving to this physical medium address. 


Figure 2-1 Disk Physical Address 


31 16 15 8 7 0 


Ps: Cylinder Track | Sector 


(Except RX01 and RX02) 


31 16 15 0 


(RX01 and RX02 Only) 


ZK0652GE 


2.1.21 RX02 Disk (VAX Only) 


On VAX systems, the RX02 disk is a mass storage device that uses removable diskettes. The RX02 supports 

existing single-density, RX01-compatible diskettes. A double-density mode allows diskettes to be recorded at 
twice the linear density. An entire diskette must be formatted in either single or double density. Mixed mode 
diskettes are not allowed. 


The RX02 is connected to the system by an RX211 controller that interfaces with the UNIBUS adapter. Up to 
two disk drives can be controlled by each RX211. 


For logical and virtual block I/O operations, data is accessed with single block resolution (four single-density 
sectors or two double-density sectors). The sector numbers are interleaved to expedite data transfers. Section 
2.2.10 describes this feature in greater detail. 


For physical block I/O operations, the track and sector parameters shown in Figure 2-1 describe a physical 
sector (128 bytes in single density; 256 bytes in double density). The driver does not apply track-to-track 
skew, cylinder offset, or sector interleaving to the physical medium address. 


2.1.22 RX23 (VAX Only) 


On VAX systems, the RX23 device is a 1-inch high, flexible diskette drive that uses 3.5-inch microfloppy 
diskettes. The RX23 drive can access standard- and high-density media. The following table summarizes 
capacities for standard- and high-density media: 


Density Unformatted Formatted 
Standard 1.0 MB 700 KB 
High 2.0 MB 1.4 MB 


The RX23 is backward compatible in that it can read 1-MB media. It can also read and write 2.0-MB 
double-sided, high-density (135 tracks per inch) media. 


The RX23 communicates with the controller using the ST506 fixed-disk interconnect (FDI). 
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2.1.23 RX33 (VAX Only) 


On VAX systems, the RX33 is a 1.2-MB, 5.25-inch, half-height diskette drive. The RX33 can record in either 
standard- or high-density mode. High-density mode provides 1.2 MB of storage using 96 tracks per inch using 
double-sided, high-density diskettes. 


In standard-density mode, the RX33 drive is read- and write-compatible with single-sided, standard-density 
RX50 diskettes. 


2.1.24 RX50 (VAX Only) 


On VAX systems, the RX50 dual-diskette drive stores data in fixed-length blocks on 5.25-inch 0.8-MB, flexible 
diskettes using preformatted headers. The RX50 can accommodate two diskettes simultaneously. 


2.1.25 RZ22, RZ23, and RZ55 Disks 


The RZ22 and RZ23 are 3.5-inch, half-height SCSI drives with an average seek rate of 33 ms and an average 
data transfer rate of 1.25 MB per second. The RZ22 and RZ23 have capacities of 52 MB and 104 MB, 
respectively. 


The RZ55 is a 332-MB, 5.25-inch, full-height SCSI drive with an average access rate of 24 ms. 


2.1.26 TU58 Magnetic Tape (DECtape II) 


The TU58 is a random-access, mass storage magnetic tape device capable of reading and writing 256 KB per 
drive of data on block-addressable, preformatted cartridges at 800 bpi. Unlike conventional magnetic tape 
systems, which store information at variable positions on the tape, the TU58 stores information at fixed 
positions on the tape, as do magnetic disk or floppy disk devices. Therefore, blocks of data can be placed on 
tape in a random fashion, without disturbing previously recorded data. In its physical geometry, the tape is 
conceptually viewed as having one cylinder, four tracks per cylinder, and 128 sectors per track. Each sector 
contains one 512-byte block. 


The TU58 uses two vectors. NUMVEC=2 is required on the CONNECT command when specifying system 
parameters. 


The TU58 interfaces with the UNIBUS adapter through a DL11-series interface device. Both the TU58 and 
the DL11 should be set to 9600 baud. (Because the TU58 is attached to a DL11, the user cannot directly 
access the TU58 registers if the TU58 is on the UNIBUS.) The TU58, which has its own controller, can access 
either one or two tape drives. 


2.2 Driver Features 
Disk drivers provide the following features: 


e Multiple controllers of the same type (except RB730), for example, more than one MBA or RK611 can be 
used on the system 


e Multiple disk drives per controller (the exact number depends on the controller) 
e Different types of disk drives on a single controller 


e Static dual porting (MBA drives only) 
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e Overlapped seeks (except RLO2, RX01, RX02, and TU58) 
e Data checks on a per-request, per-file, or per-volume basis (except RX01 and RX02) 
e Full recovery from power failure for online disk drives with volumes mounted 


e Extensive error recovery algorithms, such as error code correction and offset (except RBO2, RLO2, RX01, 
RX02, and TU58); for DSA disks, these algorithms are implemented in the controller 


e Dynamic, as well as static, bad block handling 

e Logging of device errors in a file that can be displayed by field service personnel or customer personnel 
e Online diagnostic support for drive level diagnostics 

e Multiple-block, noncontiguous, virtual I/O operations at the driver level 

e Logical-to-physical sector translation (RX01 and RX02 only) 


The following sections describe these features in greater detail. 


2.2.1 Dual-Pathed Disks 


A dual-pathed disk is a dual-ported disk that is accessible to all the CPUs in the cluster, not just to the 
CPUs that are connected physically to the disk. Dual-pathed disks can be any of the following: 


e Dual-ported MASSBUS disks 

e Dual-ported HSC disks 

e Dual-pathed DSA disks on local UDA50, KDA50, and KDB50 controllers 
e Dual-ported RF-series disks 


The term dual-pathed refers to the two paths through which clustered CPUs can access a disk to which they 
are not directly connected. If one path fails, the disk is accessed over the other path. (Note that with a 
dual-ported MASSBUS disk, a CPU directly connected to the disk always accesses it locally.) 
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2.2.2 Dual Porting MASSBUS Disks 


The MASSBUS disk drivers, DBDRIVER and DRDRIVER, support static dual porting. Dual porting allows 
two MASSBUS controllers to access the same disk drive. Figure 2-2 shows this configuration. The RP05, 
RPO6, RPO7, RM03, RM05, and RM80 disk drives can be ordered, or upgraded in the field, with the 
MASSBUS dual-port option. 


Figure 2-2 Dual-Ported Disk Drives 


Controller Controller 


ZKO650GE 


2.2.2.1 Port Selection and Access Modes 


The port select switches, on each disk drive, select the ports from which the drive can be accessed. A drive can 
be in one of the following access modes: 


e Locked on Port A—The drive is in a single-port mode (Port A). It does not respond to any request on Port 
B. 


e Locked on Port B—The drive is in a single-port mode (Port B). It does not respond to any request on Port 
A. 


e Programmable A/B—The drive is capable of responding to requests on either Port A or Port B. In this 
mode, the drive is always in one of the following states: 


— The drive is connected and responding to a request on Port A. It is closed to requests on Port B. 
— The drive is connected and responding to a request on Port B. It is closed to requests on Port A. 


— The drive is in a neutral state. It is equally available to requests on either port on a first-come, 
first-serve basis. 


The operational condition of the drive cannot be changed with the port select switches after the drive becomes 
ready. To change from one mode to another, the drive must be in a nonrotating condition. After the new mode 
selection has been made, the drive must be restarted. 


If a drive is in the neutral state and a disk controller either reads or writes to a drive register, the drive 
immediately connects a port to the requesting controller. For read operations, the drive remains connected for 
the duration of the operation. For write operations, the drive remains connected until a release command is 
issued by the device driver or a 1-second timeout occurs. After the connected port is released from its 
controller, the drive checks the other port's request flag to determine whether there has been a request on 
that port. If no request is pending, the drive returns to the neutral state. 
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2.2.2.2 Disk Use and Restrictions 


If the volume is mounted foreign, read/write operations can be performed at both ports provided the user 
maintains control of where information is stored on the disk. 


The Autoconfigure utility currently may not be able to locate the nonactive port. For example, if a dual-ported 
disk drive is connected and responding at Port A, the CPU attached to Port B might not be able to find Port B 
with the Autoconfigure utility. If this problem occurs, execute the AUTOCONFIGURE ALL/LOG command 
after the system is running. 


2.2.2.3. Restriction on Dual-Ported Non-DSA Disks in a Cluster 


Do not use SYSGEN to AUTOCONFIGURE or CONFIGURE a dual-ported, non-DSA disk that is already 
available on the system through use of an MSCP server. Establishing a local connection to the disk when a 
remote path is already known creates two uncoordinated paths to the same disk. Use of these two paths may 
corrupt files and data on any volume mounted on the drive. 


NOTE If the disk is not dual-ported or is never served by an MSCP server on the remote host, this 
restriction does not apply. 


In a cluster, dual-ported non-DSA disks (MASSBUS or UNIBUS) can be connected between two nodes of the 
cluster. These disks can also be made available to the rest of the cluster using the MSCP server on either or 
both of the hosts to which a disk is connected. 


If the local path to the disk is not found during the bootstrap, then the MSCP server path from the other host 
will be the only available access to the drive. The local path will not be found during a boot if any of the 
following conditions exist: 


e The port select switch for the drive is not enabled for this host. 
e The disk, cable, or adapter hardware for the local path is broken. 
e There is sufficient activity on the other port to hide the existence of the port. 


e The system is booted in such a way that the SYSGEN AUTOCONFIGURE ALL command in the 
SYS$SYSTEM:STARTUP.COM procedure was not executed. 


Use of the disk is still possible through the MSCP server path. 


After the configuration of the disk has reached this state, it is important not to add the local path back into 
the system I/O database. Because the operating system does not provide an automatic method for adding this 
local path, the only possible way that you can add this local path is to use the System Generation utility 
(SYSGEN) qualifiers AUTOCONFIGURE or CONFIGURE to configure the device. SYSGEN is currently not 
able to detect the presence of the disk's MSCP path, and will incorrectly build a second set of data structures 
to describe it. Subsequent events could lead to incompatible and uncoordinated file operations, which might 
corrupt the volume. 


To recover the local path to the disk, it is necessary to reboot the system connected to that local path. 


2.2.3 Dual-Pathed DSA Disks 


A dual-ported DSA disk can be failed over between the two CPUs that serve it to the cluster under the 
following conditions: (1) the same disk controller letter and allocation class are specified on both CPUs and (2) 
both CPUs are running the MSCP server. 


CAUTION Failure to observe these requirements can endanger data integrity. 
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However, because a DSA disk can be on line to only one controller at a time, only one of the CPUs can use its 
local connection to the disk. The second CPU accesses the disk through the MSCP server. If the CPU that is 
currently serving the disk fails, the other CPU detects the failure and fails the disk over to its local 
connection. The disk is thereby made available to the cluster once more. 


NOTE A dual-ported DSA disk may not be used as a system disk. 


2.2.4 Dual-Porting HSC Disks 


By design, HSC disks are cluster accessible; therefore, if they are dual-ported, they are automatically 
dual-pathed. CI-connected CPUs can access a dual-pathed HSC disk by way of a path through either 
HSC-connected device. 


For each dual-ported HSC disk, you can control failover to a specific port using the port select buttons on the 
front of each drive. By pressing either port select button (A or B) on a particular drive, you can cause the 
device failover to the specified port. 


With the port select button, you can select alternate ports to balance the disk controller workload between 
two HSC subsystems. For example, you could set half of your disks to use port A and set the other half to use 
port B. 


The port select buttons also allow you to fail over all the disks to an alternate port manually when you 
anticipate the shutdown of one of the HSC subsystems. 


2.2.5 Dual-Pathed RF-Series Disks 


In a dual-path configuration of MicroVAX 3300/3400 CPUs or MicroVAX 3800/3900 CPUs using RF-series 
disks, CPUs have concurrent access to any disk on the DSSI bus. A single disk is accessed through two paths 
and can be served to all satellites by either CPU. 


If either CPU fails, satellites can access their disks through the remaining CPU. Note that failover occurs in 
the following situations: (1) when the DSSI bus is connected between SII integral adapters on both MicroVAX 
3300/3400 CPUs or (2) when the DSSI bus is connected between the KFQSA adapters on pairs of MicroVAX 
3300/3400s or pairs of MicroVAX 3800/3900s. 


NOTE The DSSI bus should not be connected between a KFQSA adapter on one CPU and an SII 
integral adapter on another. 


2.2.6 Data Check 


A data check is made after successful completion of a read or write operation and, except for the TU58, 
compares the data in memory with the data on disk to make sure they match. 


Disk drivers support data checks at the following levels: 


e Per request—You can specify the data check function modifier (IO$M_DATACHECK) on a read logical 
block, write logical block, read virtual block, write virtual block, read physical block, or write physical 
block operation. IO$M_DATACHECK is not supported for the RX01 and RX01 drivers. 


e Per volume—You can specify the characteristics “data check all reads” and “data check all writes” when 
the volume is mounted. The HP OpenVMS DCL Dictionary describes volume mounting and dismounting. 
The HP OpenVMS System Services Reference Manual describes the Mount Volume (S$MOUNT) and 
Dismount Volume ($DISMOU) system services. 
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e Per file—You can specify the file access attributes “data check on read” and “data check on write.” File 
access attributes are specified when the file is accessed. Chapter 1 of this manual and the OpenVMS 
Record Management Services Reference Manual describe file access. 


Offset recovery is performed during a data check, but error code correction (ECC) is not performed (see 
Section 2.2.9). For example, if a read operation is performed and an ECC correction is applied, the data check 
would fail even though the data in memory is correct. In this case, the driver returns a status code indicating 
that the operation was completed successfully, but the data check could not be performed because of an ECC 
correction. 


Data checks on read operations are extremely rare, and you can either accept the data as is, treat the ECC 
correction as an error, or accept the data but immediately move it to another area on the disk volume. 


A data check operation directed to a TU58 does not compare the data in memory with the data on tape. 
Instead, either a read check or a write check operation is performed (see Sections Section 2.4.1 and Section 
2.4.2). 


2.2.7 Effects of a Failure During an I/O Write Operation 


The operating system ensures that when an I/O write operation returns a successful completion status, the 
data is available on the disk or tape media. Applications that must guarantee the successful completion of a 
write operation can verify that the data is on the media by specifying the data check function modifier 
IO$M_DATACHECK. Note that the IO$M_DATACHECK data check function, which compares the data in 
memory with the data on disk, affects performance because the function incurs the overhead of an additional 
read operation to the media. 


If a system failure occurs while a multiple-block write operation is in progress, the operating system does not 
guarantee the successful completion of the write operation. (OpenVMS does guarantee single-block write 
operations to DSA drives.) When a failure interrupts a write operation, the data may be left in any one of the 
following conditions: 


e The new data is written completely to the disk blocks on the media, but a completion status was not 
returned before the failure. 


e The new data is partially written to the media so that some of the disk blocks involved in the I/O contain 
the data from the write operation in progress, and the remainder of the blocks contain the data that was 
present before the write operation. 


e The new data was never written to the disk blocks on the media. 


To guarantee that a write operation either finishes successfully or (in the event of failure) is redone or rolled 
back as if it were never started, use additional techniques to ensure data correctness and recovery. For 
example, using database journaling and recovery techniques allows applications to recover automatically 
from failures such as the following: 


e Permanent loss of the path between a CPU data buffer containing the data being written and the disk 
being written to during a multiple-block I/O operation. Communication path loss can occur due to node or 
controller failure or a failure of node-to-node communications. 


e Failure of a CPU (such as a system failure, system halt, power failure, or system shutdown) during a 
multiple-block write operation. 


e Mistaken deletion of a file. 
e Corruption of file system pointers. 
e File corruption due to a software error or incomplete bucket write operation to an indexed file. 


e Cancellation of an in-progress multiple-block write operation. 
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2.2.8 Overlapped Seeks 


A seek operation involves moving the disk read/write heads to a specific place on the disk without any 
transfer of data. All transfer functions, including data checks, are preceded by an implicit seek operation 
(except when the seek is inhibited by the physical I/O function modifier IO$M_INHSEEK). Seek operations 
can be overlapped except on RLO2, RX01, RX02, TU58 drives, MicroVAX 2000, VAXstation 2000, or on 
controllers with diskettes (for example, RQDX3) when the disk is executing I/O requests. That is, when one 
drive performs a seek operation, any number of other drives can also perform seek operations. 


During the seek operation, the controller is free to perform transfers on other units. Therefore, seek 
operations can also overlap data transfer operations. For example, at any one time, seven seeks and one data 
transfer could be in progress on a single controller. 


This overlapping is possible because, unlike I/O transfers, seek operations do not require the controller once 
they are initiated. Therefore, seeks are initiated before I/O transfers and other functions that require the 
controller for extended periods. 


All DSA controllers perform extensive seek optimization functions as part of their operation; 
IO$M_INHSEEK has no effect on these controllers. 


2.2.9 Error Recovery 


Error recovery in the operating system is aimed at performing all possible operations to complete an I/O 
operation successfully. Error recovery operations fall into the following categories: 


e Handling special conditions such as power failure and interrupt timeout. 


e Retrying nonfatal controller and drive errors. For DSA and SCSI disks, this function is implemented by 
the controller. 


e Applying error correction information (not applicable for RB02, RLO2, RX01, RX02, and TU58 drives). For 
DSA and SCSI disks, error correction is implemented by the controller. 


e Offsetting read heads to try to obtain a stronger recorded signal (not applicable for RB02, RLO2, RB80, 
RM80, RX01, RX02, and TU58 drives). For DSA and SCSI disks, this function is implemented by the 
controller. 


The error recovery algorithm uses a combination of these four types of error recovery operations to complete 
an I/O operation: 


e Power failure recovery consists of waiting for mounted drives to spin up and come on line, followed by 
reexecution of the I/O operation that was in progress at the time of the power failure. 


e Device timeout is treated as a nonfatal error. The operation that was in progress when the timeout 
occurred is reexecuted up to eight times before a timeout error is returned. 


e Nonfatal controller/drive errors are executed up to eight times before a fatal error is returned. 


e All normal error recovery procedures (nonspecial conditions) can be inhibited by specifying the inhibit 
retry function modifier IO$M_INHRETRY). If any error occurs and this modifier is specified, the virtual, 
logical, or physical I/O operation is immediately terminated, and a failure status is returned. This 
modifier has no effect on power recovery and timeout recovery. 


2.2.9.1 Skip Sectoring 


Skip sectoring is a bad block treatment technique implemented on R80 disk drives (the RB80 and RM80 
drives). In each track of 32 sectors, one sector is reserved for bad block replacement. Consequently, an R80 
drive has available only 31 sectors per track. The Get Device/Volume Information ($GETDVI) system service 
returns this value. 
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You can detect bad blocks when a disk is formatted. Most formatters place these blocks in a bad block file. On 
an R80 drive, the first bad block encountered on a track is designated as a skip sector. This is accomplished by 
setting a flag in the sector header on the disk and placing the block in the skip sector file. 


When a skip sector is encountered during a data transfer, it is skipped over, and all remaining blocks in the 
track are shifted by one physical block. For example, if block number 10 is a skip sector, and a transfer 
request was made beginning at block 8 for four blocks, then blocks 8, 9, 11, and 12 will be transferred. Block 
10 will be skipped. 


Because skip sectors are implemented at the device driver level, they are not visible to you. The device 
appears to have 31 contiguous sectors per track. Sector 32 is not directly addressable, although it is accessed 
if a skip sector is present on the track. 


2.2.10 Logical-to-Physical Translation (RX01 and RX02) 


Logical-block-to-physical-sector translation on RX01 and RX02 drives adheres to the standard format. For 
each 512-byte logical block selected, the driver reads or writes four 128-byte physical sectors (or two 256-byte 
physical sectors if an RX02 is in double-density mode). To minimize rotational latency, the physical sectors 
are interleaved. Interleaving allows the processor time to complete a sector transfer before the next sector in 
the block reaches the read/write heads. To allow for track-to-track switch time, the next logical sector that 
falls on a new track is skewed by six sectors. (There is no interleaving or skewing on read physical block and 
write physical block I/O operations.) Logical blocks are allocated starting at track 1; track 0 is not used. 


The translation procedure, in more precise terms, is as follows: 


1. Compute an uncorrected medium address using the following dimensions: 
Number of sectors per track = 26 Number of tracks per cylinder = 1 Number of cylinders per disk = 77 


2. Correct the computed address for interleaving and track-to-track skew (in that order) as shown in the 
following HP Fortran for OpenVMS statements. ISECT is the sector address and ICYL is the cylinder 
address computed in Step 1. 


Interleaving: 


ITEMP = ISECT*2 


IF (ISECT .GT. 12) ITEMP = ITEMP-25 
ISECT = ITEMP 
Skew: 


ISECT = ISECT+ (6*ICYL) 


ISECT = MOD (ISECT, 26) 


3. Set the sector number in the range of 1 through 26 as required by the hardware: 


ISECT = ISECT+1 


4. Adjust the cylinder number to cylinder 1 (cylinder 0 is not used): 


ICYL = ICYL+t1 


2.2.11 DIGITAL Storage Architecture (DSA) Devices 


The DIGITAL Storage Architecture (DSA) is a collection of specifications that cover all aspects of a mass 
storage product. The specifications are grouped into the following general categories: 


e Media format—Describes the structure of sectors on a disk and the algorithms for replacing bad blocks 
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e Drive-to-controller interconnect—Describes the connection between a drive and its controller 
e Controller-to-host communicationsé—Describes how hosts request controllers to transfer data 


Because the operating system supports all DSA disks, it supports all controller-to-host aspects of DSA. Some 
of these disks, such as the RA60, RA80, and RA81, use the standard drive-to-controller specifications. Other 
disks, such as the RC25, RD51, RD52, RD53, and RX50, do not. Disk systems that use the standard 
drive-to-controller specifications employ the same hardware connections and use the HSC50, KDA50, KDB50, 
and UDAS0 interchangeably. Disk systems that do not use the drive-to-controller specifications provide their 
own internal controller, which conforms to the controller-to-host specifications. 


DSA disks differ from MASSBUS and UNIBUS disks in the following ways: 


e DSA disks contain no bad blocks. The hardware and the disk class driver (DUDRIVER) function to ensure 
a logically contiguous range of good blocks. If any block in the user area of the disk develops a defective 
area, all further access to that block is revectored to a spare good block. Consequently, it is never 
necessary to run the Bad Block Locator utility (BAD) on DSA disks. There is no manufacturer's bad block 
list and the file BADBLK.SYS is empty. (The Verify utility, which is invoked by the ANALYZE 
/DISK_STRUCTURE /READ_CHECK command, can be used to check the integrity of newly received 
disks.) See Section 2.2.11.1 for more information about bad block replacement for DSA disks. 


e Insert a WAIT statement in your SYSTARTUP_V5.COM file on VAX systems, or your 
SYSTARTUP_VMS.COM file on Alpha systems, prior to the first MOUNT statement for a DSA disk. The 
wait period should be about 2 to 4 seconds for the UDA50 and about 30 seconds for the HSC50. The wait 
time is controller-dependent and can be as much as several minutes if the controller is offline or otherwise 
inoperative. If this wait is omitted, the MOUNT request may fail with a “no such device” status. 


e The DUDRIVER and the DSA device controllers allow multiple, concurrently outstanding QIO requests. 
The order in which these requests complete might not be in the order in which they were issued. 


e All DSA disks can be dual-ported, but only one HSC/UDA controller can control a disk at a time (see 
Section 2.2.3). 


e Inmany cases, you can attach a DSA disk to its controller on a running system and then use it without 
manual intervention. 


e DSA disks and the DUDRIVER do not accept physical QIO data transfers or seek operations. 


2.2.11.1 Bad Block Replacement and Forced Errors for DSA Disks 


Disks that are built according to the DSA specifications appear to be error free. Some number of logical blocks 
are always capable of recording data. When a disk is formatted, every user-addressable logical block is 
mapped to a functioning portion of the actual disk surface, which is known as a physical block. The physical 
block has the true data storage capacity represented by the logical block. 


Additional physical blocks are set aside to replace blocks that fail during normal disk operations. These extra 
physical blocks are called replacement blocks. Whenever a physical block to which a logical block is 
mapped begins to fail, the associated logical block is remapped (revectored) to one of the replacement blocks. 
The process that revectors logical blocks is called a bad block replacement operation. Bad block 
replacement operations use data stored in a special area of the disk called the Replacement and Caching 
Table (RCT). 


When a drive-dependent error threshold is reached, the need for a bad block replacement operation is 
declared. Depending on the controller involved, the bad block replacement operation is performed either by 
the controller itself (as is the case with HSCs) or by the host (as is the case with UDAs). In either case, the 
same steps are performed. After inspecting and altering the RCT, the failing block is read and its contents are 
stored in a reserved section of the RCT. 
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The design goal of DSA disks is that this read operation proceeds without error and that the RCT copy of the 
data is correct (as it was originally written). The failing block is then tested with one or more data patterns. If 
no errors are encountered in this test, the original data is copied back to the original block and no further 
action is taken. If the data-pattern test fails, the logical block is revectored to a replacement block. After the 
block is revectored, the original data is copied back to the revectored logical block. In all these cases, the 
original data is preserved and the bad block replacement operation occurs without the user being aware that 
it happened. 


However, if the original data cannot be read from the failing block, a best-attempt copy of the data is stored in 
the RCT and the bad block replacement operation proceeds. When the time comes to write back the original 
data, the best-attempt data (stored in the RCT) is written back with the forced error flag set. The forced 
error flag is a signal that the data read is questionable. Reading a block that contains a forced error flag 
causes the status SS$_FORCEDERROR to be returned. This status is displayed by the following message: 


SSYSTEM-F-FORCEDERROR, forced error flagged in last sector read 


Writing into a block always clears the forced error flag. 


Note that most utilities and DCL commands treat the forced error flag as a fatal error and terminate 
operation when they encounter it. However, the Backup utility (BACKUP) continues to operate in the 
presence of most errors, including the forced error. BACKUP continues to process the file, and the forced error 
flag is lost. Thus, data that was formerly marked as questionable may become correct data. 


System managers (and other users of BACKUP) should assume that forced errors reported by BACKUP 
signal possible degradation of the data. 


To determine what, if any, blocks on a given disk volume have the forced error flag set, use the ANALYZE 
/DISK_STRUCTURE /READ_CHECK command, which invokes the Verify utility. The Verify utility reads 
every logical block allocated to every file on the disk and then reports (but ignores) any forced error blocks 
encountered. 


2.2.12 VAXstation 2000 and MicroVAX 2000 Disk Driver 


The VAXstation 2000 and MicroVAX 2000 disk driver supports some DSA disk operation. In particular, the 
driver supports block revectoring and bad block replacement. This provides the system with a logically perfect 
disk medium. 


Like other DSA disks, if a serious error occurs during a replacement operation, the disk is write-locked to 
prevent further changes. This is done to preserve data integrity and minimize damage that could be caused 
by failing hardware. Unlike other DSA disks, there is no visible indication on the drive itself that the disk is 
write-locked. However, the following indicators help you determine that the disk has become write-protected: 


e ERRFMT messages show that the disk is write-locked. 
e The disk enters mount verification and hangs. 
e DCL command SHOW DEVICE output shows that the disk is write-locked. 
e Error messages occur from programs and utilities attempting to write to the disk. 
If the disk becomes write-locked, you should use the following procedure: 
1. Shut down the system. 
2. Use standalone BACKUP to create a full backup of the disk. 
3. Format the disk with the disk formatter. 


4. Restore the disk from the backup using standalone BACKUP. Note that any files with sectors flagged 
with a forced error may be corrupted and may need to be restored from a previous backup. 
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If errors occurring during replacement operations persist, call HP Customer Services. 


2.2.13 SCSI Disk Class Driver 


The VAXstation 3100, 3520, and 3540 contain a SCSI bus that provides access to as many as seven SCSI 
disks. The SCSI disk class driver controls SCSI disks on all of the above systems. Although SCSI disks do not 
conform to DSA, they do support the following error recovery features: 


e Static and dynamic bad block replacement (BBR) 

e Error correction code (ECC) 

e Reexecution of read or write operations within the SCSI drive 

e Reexecution of read or write operations by the SCSI disk class driver 


All SCSI disks supplied by HP implement the REASSIGN BLOCKS command, which relocates data for a 
specific logical block to a different physical location on the disk. The SCSI disk class driver reassigns the block 
in the following instances: (1) when the retry threshold is exceeded during an attempt to read or write a block 
of data on the disk or (2) when an irrecoverable error occurs during a write operation. 


Unlike DSA, there is no forced error flag in SCSI. Blocks that produce irrecoverable errors during read 
operations are not reassigned in order to prevent undetected loss of user data. Instead, the SCSI disk class 
driver returns the SS$_PARITY status whenever a read operation results in an irrecoverable error. 


2.2.14 Audio Extensions to the SCSI Disk Class Driver 


This section describes SCSI disk class driver audio commands and the $QIO interface by which the operating 
system provides audio functionality to the SCSI disk. 

Table 2-1 lists the SCSI audio commands supported by the SCSI disk class driver. 

Table 2-1 SCSI Disk Class Driver Audio Commands 


Command Audio Function Code! Description 


Play Audio AUDIO_PLAY_AUDIO_MSF (5) Requests the CD-ROM to begin an audio playback 

MSF operation. The two required command arguments 
specify absolute starting and ending addresses of the 
playback in terms of minutes, seconds, and frame 


(MSF). 
Play Audio AUDIO_PLAY_AUDIO_TRACK Requests the CD-ROM to begin an audio playback 
Track (6) operation. The two required command arguments 


specify the starting and ending tracks of the playback 
in terms of track number and index. 


Play Audio AUDIO_PLAY_AUDIO (4) Requests the CD-ROM to begin an audio playback 
operation. The two required command arguments 
specify the starting logical block address (LBA) and 
the transfer count, in blocks, of the playback. 


Pause AUDIO_PAUSE (0) Requests the CD-ROM to suspend any active audio 
operations. In response, the CD-ROM enters the 
hold-track state, muting the audio output after 
playing the current block. 
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Table 2-1 SCSI Disk Class Driver Audio Commands (Continued) 
Command Audio Function Code! Description 
Resume AUDIO_RESUME (1) Requests the CD-ROM to resume any active audio 


operations. In response, the CD-ROM exits the 
hold-track state and resumes playback at the block 
following the last block played. 


Get Status AUDIO_GET_STATUS (9) Requests from the CD-ROM the status of the 
currently active playback operation, as well as the 
state of the current block. The Get Status command 
corresponds to the SCSI II Read Sub-channel 
command (READ SUBQ). 


Set Volume AUDIO_SET_VOLUME (11) Requests the CD-ROM to adjust the output channel 
selection and volume settings for ports 0 through 3. 
The Set Volume command corresponds to the SCSI II 
Mode Select command for the CD-ROM Audio 
Control Parameters page. 


Get Volume AUDIO_GET_VOLUME (12) Requests from the CD-ROM the output channel 
selection and volume settings for ports 0 through 3. 
The Get Volume command corresponds to the SCSI II 
Mode Sense command for the CD-ROM Audio 
Control Parameters page. 


Prevent AUDIO_PREVENT_REMOVAL Prevents the removal of the CD caddy from the 
Removal (2) CD-ROM drive. 

Allow AUDIO_ALLOW_REMOVAL (3) Allows the removal of the CD caddy from the 
Removal CD-ROM drive. 

Get TOC AUDIO_GET_TOC (10) Requests from the CD-ROM a list of each track on 


the disk, including information about the audio or 
data contents of each track. Applications that require 
a detailed knowledge of the organization of a 
CD-ROM can use this function to obtain that 
information. The Get TOC command corresponds to 
the SCSI II Read TOC command. 


1. Symbolic values for the function codes of SCSI audio commands are defined in 
SYS$EXAMPLES:CDVERIFY.C. Numeric values appear within parentheses in this table column. 


2.2.14.1 $QIO Interface to Audio Functionality of the SCSI Disk Class Driver 


To employ the audio functions of the RRD42 CD-ROM reader, the application program issues a call to the 
$QIO system service using the following format: 


status=SYSSQIO ([efn] ,[chan] ,func [,iosb] [,astadr] [,astprm] [,p1] [,p2] [,p3] [,p4] [,p5] 
[,p6]) 


Arguments 
[efn] 
[chan] 
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Liosb] 
[astadr] 
[astprm] 


These arguments apply to the $QIO system service completion, not to device interrupt actions. For an 
explanation of these arguments, refer to the description of the $QIO system service in the HP OpenVMS 
System Services Reference Manual. 


func 

The IO$_AUDIO function code allows the SCSI disk class driver to process SCSI audio commands. 

pl 

Address of an audio control block (AUCB). The $QIO system service passes a SCSI audio command and 


command-specific control information to the SCSI disk class driver in the AUCB structure (see Section 
2.2.14.2). 


p2 
Size of the AUCB. 
2.2.14.2 Defining an Audio Control Block (AUCB) 


An application program that issues a call to the $QIO system service that specifies the IO$_AUDIO function 
code in the func argument must supply the address of an AUCB structure in the p1 argument and its size in 
the p2 argument. 
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An AUCB defines a specific SCSI audio command and provides the SCSI disk class driver with 
command-specific arguments and control information. Table 2-2 defines the fields that appear in an AUCB; 
these fields are shown in Figure 2-3. See SYS$EXAMPLES:CDROM_AUDIO.C for a code example that shows 
how an AUCB is defined in the C programming language. 


Figure 2-3 Audio Control Block (AUCB) 


ZK4625A 


Table 2-2 Contents of AUCB 


Field Use 


AudioFunction Numeric or symbolic code representing the audio function desired by the application 
Code program. (See Table 2-1.) The application program must provide a valid audio function 
code for each operation. 


AUCB Version Version of the AUCB and SCSI disk class driver audio interface. For the current version 


Number of the interface the value of this field should be 1. This field must never contain a zero. 
Argument 1 This field is audio command-specific and contains the first argument of the function as 
follows: 
Audio Function Code! Field Contents 
AUDIO_PLAY_AUDIO_MSF (5) Starting Frames | (Sec shifted left 8 bits) | (Min 


shifted left 16 bits) 
AUDIO_PLAY_AUDIO_TRACK (6) Starting (Track shifted left 8 bits) | Index 


AUDIO_PLAY_AUDIO (4) Starting logical block address. 

AUDIO_GET_STATUS (9) 0 if LBA format, 1 if MSF format. Refer to the 
SCSI II specification for information about these 
formats. 
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Table 2-2 Contents of AUCB (Continued) 
Field Use 
AUDIO_SET_VOLUME (11) Longword representing the values to be used to 
determine the new output channel selection and 
volume settings for CD-ROM ports 0 through 3. 
Figure 2-4 shows the format of this longword. 
Note that many CD-ROM drives do not support 
ports 2 and 3. 
AUDIO_GET_VOLUME (12) Longword to receive the current values 
determining output channel selection and volume 
settings for CD-ROM ports 0 through 3. Figure 2-4 
shows the format of this longword. Note that 
many CD-ROM drives do not support ports 2 and 
3. 
AUDIO_GET_TOC (10) 0 if LBA format, 1 if MSF format. Refer to the 
SCSI II specification for information about these 
formats. 
Argument 2 This field is audio command-specific and contains the second argument of the function as 
follows: 
Audio Function Code! Field Contents 
AUDIO_PLAY_AUDIO_MSF (5) Starting frames | (sec shifted left 8 bits) | (min 
shifted left 16 bits) 
AUDIO_PLAY_AUDIO_TRACK (6) Ending(track shifted left 8 bits) | index 
AUDIO_PLAY_AUDIO (4) Transfer count in number of contiguous blocks to 
be played 
AUDIO_GET_TOC (10) Starting track 
Reserved Must be zero. 
Destination Address of the application program's buffer from which the status from a GET_STATUS 
Buffer Address or GET_TOC function is returned. 
Destination Size, in bytes, of the destination buffer specified in the Destination Buffer Address field. 
Buffer Count For the GET_STATUS function, this field must contain the value 48 to receive complete 
status information. For the GET_TOC function, this field must contain the value 804 to 
receive full status. The SCSI disk class driver truncates the status data, if the 
destination buffer size is smaller than the size of the data. 
Destination The SCSI disk class driver returns to this field the actual number of bytes transferred to 
Buffer the buffer specified in the Destination Buffer Address field. 


Transfer Count 


Before accessing data returned by the GET_TOC or GET_STATUS commands, an 
application program must check the contents of this field to determine precisely how 
many bytes were returned by the CD-ROM. 


The application program initializes this field to zero. 
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Table 2-2 Contents of AUCB (Continued) 
Field Use 

Operating Completion status of the SCSI audio function. This value is also returned in the I/O 

System status block of specified in the iosb argument to the $QIO system service call. See 

Command Table 2-3 for a description of these status codes. 

Stetus The application program initializes this field to zero. 

SCSI SCSI status of the current operation. The SCSI disk class driver returns the SCSI status 

Command byte for the SCSI audio command described by this AUCB in the low byte of the 

Status low-order word of this field. It returns the sense key in the low byte of the high-order 

(optional) word. Refer to the SCSI specification for information regarding SCSI status and SCSI 
sense keys. 
The application program initializes this field to zero. 

Sense Data Address of buffer to which the SCSI disk class driver returns sense data when errors 

Buffer Address occur during audio function execution. When this field is specified, in the event of a check 

(optional) condition on an Audio command, the SCSI disk class driver automatically issues a 
Request Sense command to retrieve the Sense Key/Sense Data from the target. The 
target returns this data to the buffer specified in this field before the failing $QIO audio 
function completes. 

Sense Data Size, in bytes, of the buffer specified in the Sense Data Buffer Address field. During 

Buffer Count request sense processing, the target device truncates the sense data to fit in this buffer. 

(optional) 

Sense Data Actual number of bytes of sense data returned to the application in the buffer specified in 

Buffer the Sense Data Buffer Address field. 

Transfer Count ee sasepate : 

(GoGonal The application program initializes this field to zero. 

Reserved Must be zero. 


1. For any function code not listed in this table, this field contains a zero. 


The output channel selection and volume settings for CD-ROM ports as used by the SET_VOLUME function 
appear as shown in Figure 2-4. 


2.2.14.3 Error Handling in Applications Using SCSI Audio Functions 


As indicated in Table 2-2, the AUCB provides for three levels of error status reporting: 


e Condition values, returned in the Operating System Command Status field of the AUCB, as well as in the 
I/O status block of specified in the iosb argument to the $QIO system service call. (See Table 2-3 for a 
description of these status codes.) 
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If this status is SS$_ NORMAL, the function has completed without error. If the status is not 
SS$_NORMAL, the application program should check the SCSI Command Status field and the Sense 
Data buffer to fully determine the cause of the failure. 


Figure 2-4 Output Channel Selection and Volume Settings for CD-ROM Ports as 


Used by the SET_VOLUME Function 
31 23 15 7 0 


output selection output selection 


Port1or3 Port 0 or 2 


volume = 00 (muted) to FF (maximum) 
output selection <7:4> = 0 


output selection <3:0> = 0000 
0001 


0010 
0011 


output muted on this channel) 

connect audio channel 0 to this output port) 
connect audio channel 1 to this output port) 
connect audio channels 0 and 1 to this port) 


ZK4626A 


SCSI command status, returned in the SCSI Command Status field of the AUCB. The SCSI disk class 
driver returns to this field SCSI status as well as the sense key in the event of a check condition SCSI 
status. The sense key can be used to determine the first level of error reporting supported by SCSI. See 
the SCSI specification for further information. 


Sense data, returned in the buffer specified in the Sense Data Buffer Address field of the AUCB. Sense 
data bytes are assigned as defined in the SCSI II specification. Sophisticated programmers can use the 
data in this to obtain detailed information about the error-causing condition. 


If the CD-ROM device is currently software-enabled (that is, the volume has been mounted) and a unit 
attention is detected, then mount verification will be initiated by the driver. However, if the CD-ROM is not 
software-enabled, the event will simply be returned to the application issuing the Audio $QIO function. 


Table 2-3 Status Codes Returned to the IOSB and AUCB by the SCSI Disk Class 
Driver 
Code Meaning 

SS$_NORMAL AUCB command completed successfully. 

SS$_ABORT Returned by the SCSI disk port driver. In general, you should retry 
commands that fail with this status. 

SS$_BADPARM The driver detected an illegal value or missing value in the AUCB. 

SS$_CTRLERR CD-ROM failed some part of its initialization sequence. When this status is 
returned, it is unlikely that the CD-ROM is usable. 

SS$_DEVOFFLINE Device returned a not-ready sense key or failed the TEST UNIT 


READY/START sequence. 
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Table 2-3 Status Codes Returned to the IOSB and AUCB by the SCSI Disk Class 
Driver (Continued) 
Code Meaning 
SS$_DRVERR CD-ROM failed to execute the command, either because the drive has failed 


or an illegal command was issued. Such a command could be a command 
that requested the drive to issue an audio command to a data track or 
attempted to perform a play operation on nonexistent tracks. 


SS$_ILLIOFUNC Illegal I/O function was specified in the func argument of the $QIO request. 
SS$_IVADDR Specified block number is larger than UCB$L_MAXBLOCK. 
SS$_MEDOFL Last command failed because the drive detected the removal and 


replacement of the CD carrier, or the unsuccessful completion of a Request 
Sense command after a check condition error. In general, you should not 
retry commands that fail with this status. 


SS$_NOPRIV Caller does not have sufficient privileges to execute this function. If the 
CD-ROM has not been mounted before an IO$ READVBLK function is 
issued, this status may be returned. 


SS$_OPINCOMPL Number of bytes requested is less than the number of bytes returned. 
SS$_PARITY Nonrecoverable media error (does not apply to audio functions). 
SS$_RECOVERR Recovered media error (does not apply to audio functions). 
SS$_VOLINV CD-ROM has not been mounted. 

SS$_WRITLCK Write operations not permitted on read-only devices. 


2.2.14.4 Using CD-ROM to Store Both Data and Audio Information 


To make effective use of mixed data and audio CDs, an application program requires detailed knowledge of 
the particular CD being played. The application program must know which tracks include data and which 
tracks include audio so it can use commands appropriate to the different track types. Issuing an audio 
command on a data track results in the command failing with a status of SS$_DRVERR. 


By default, the SCSI disk class driver transfers all requests issued to a CD-ROM in blocks of 512 bytes. This 
byte amount is referred to as the default block size. Before attempting to issue READ operations to the 
CD-ROM, you must ensure that the CD-ROM has been mounted as foreign or as a Files-11 volume. The 
application program can then determine, by issuing a GET_TOC function, which tracks (and, therefore, which 
logical blocks) contain data and which contain audio information. 


2.2.14.5 Programming Audio Applications 


The following list contains information useful in avoiding problems when writing code using the SCSI audio 
interfaces: 


e Ifyou do not know the type of file system on the CD-ROM, you should mount the CD-ROM as foreign and 
issue a $QIO request with the logical block I/O read function (IO$_READLBLK) to read individual data 
blocks. The default block size for all CD-ROMs is 512 bytes. 
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e When using the GET_TOC command to obtain CD-ROM address information in LBA format, be advised 
that the byte ordering of the returned data is in big-endian form. Because VAX byte ordering is 
little-endian, you must switch the LBA data bytes to get a logical block address that is valid on a VAX 
computer. SYS$SEXAMPLES:CDROM_AUDIO.C contains an example of how to perform this exchange. 


¢ Before attempting to issue a $QIO request with the virtual block I/O read function (IO$_READVBLK) to 
the CD-ROM, ensure that the CD-ROM has been mounted. Typically, you have to foreign mount 
non-Files-11 disks. If an IO$_READVBLK $QIO request is issued to an unmounted CD, the request fails 
with a status of SS$_NOPRIV. 

2.2.14.6 Application Program Example Using SCSI Audio Capabilities (VAX only) 


The file SYS$EXAMPLES:CDROM_AUDIO.C contains an example of an application program that performs 
the following tasks: 


e Defines standard symbolic names for the audio function codes representing SCSI audio commands. 
e Defines representative AUCBs for each audio function code supported by the SCSI disk class driver. 


e Issues a series of $QIO system service requests, each specifying the IO$_AUDIO function, that exercise 
the SCSI disk class driver to test its support for CD-ROM drives with audio capabilities. 


e Converts LBA data returned by a GET_STATUS command in big-endian byte-ordering form to VAX 
little-endian byte-ordering form. 


2.3 Disk Driver Device Information 


You can obtain information on all disk device characteristics by using the Get Device/Volume Information 
($GETDVD system service (refer to the HP OpenVMS System Services Reference Manual). 


$GETDVI returns disk characteristics when you specify the item codes DVI$_DEVCHAR and 
DVI$_DEVCHAR2. Table 2-4 lists the possible characteristics for disk devices. 


Table 2-4 Disk Device Characteristics 


Characteristic! Meaning 


Dynamic Bits (Conditionally Set) 


DEV$M_AVL Device is on line and available. 

DEV$M_CDP? ? Dual-path device with two unit control blocks (UCBs). 
DEV$M_CLU2 Device is available clusterwide. 

DEV$M_2P2 Device is dual-pathed. 

DEV$M_FOR Device is foreign. 

DEV$M_MNT Volume is mounted. 

DEV$M_RCK Perform data check on all reads. 
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Table 2-4 Disk Device Characteristics (Continued) 
Characteristic! Meaning 
DEV$M_WCK Perform data check on all writes. 
DEV$M_MSCP2 Device is accessed using the mass storage control protocol. 
DEV$M_RCT Disk contains replacement and caching table. 
DEV$M_SRV2 For a cluster, device is served by the MSCP server. 
Static Bits (Always Set) 

DEV$M_FOD Device is file-oriented. 
DEV$M_IDV Device is capable of input. 
DEV$M_ODV Device is capable of output. 
DEV$M_RND Device is capable of random access. 
DEV$M_SHR Device is shareable. 


1. Defined by the $DEVDEF macro. 
2. These bits are located in DVI$_ DEVCHAR2. 
3. MASSBUS only. 


DVI$_DEVBUFSIZ returns the buffer size. The buffer size is the default to be used for disk transfers (this 
default is normally 512 bytes). DVI$_DEVTYPE and DVI$_DEVCLASS return the device type and class 
names, which are defined by the $DCDEF macro. The disk model determines the device type. For example, 
the device type for the RA81 is DT$_RA81. (Foreign device types take the form DT$_FD1 through DT$_FD8.) 
The device class for disks is DC$_DISK. 


DVI$_CYLINDERS returns the number of cylinders per volume (that is, per disk), DVI$_TRACKS returns 
the number of tracks per cylinder, and DVI$_SECTORS returns the number of sectors per track. Values are 
returned as 4-byte decimal numbers. 


DVI$_MAXBLOCK returns the maximum number of blocks (1 block = 512 bytes) that can be contained on the 
volume (that is, on the disk). Values are returned as 4-byte decimal numbers. This information can be used, 
for example, to determine the density of an RX02 diskette (single density = 494 blocks, double density = 988 
blocks). 


2.4 Disk Function Codes 


Disk drivers can perform logical, virtual, and physical I/O functions. Foreign-mounted devices do not require 
privilege to perform logical and virtual I/O requests. 


Logical and physical I/O functions allow access to volume storage and require only that the issuing process 
have access to the volume; however, DSA disks and the disk class driver (DUDRIVER) do not accept physical 
QIO data transfers or seek operations. 
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NOTE The results of logical and physical I/O operations are unpredictable if an ancillary control 
process (ACP) or extended QIO processing (XQP) is present. 


Virtual I/O functions require an ACP for Files-11 On-Disk Structure Level 1 files or an XQP for Files-11 
On-Disk Structure Level 2 files. Virtual I/O functions must be executed in a prescribed order. First, you create 
and access a file, then you write information to that file, and lastly you deaccess the file. Subsequently, when 
you access the file, you read the information and then deaccess the file. Delete the file when the information is 
no longer useful. 


Non-DSA disk devices can read or write up to 65,535 bytes in a single request. DSA devices connected to an 
HSC50 can transfer up to 4 billion bytes in a single request. In all cases, the maximum size of the transfer is 
limited by the number of pages that can be faulted into the process' working set, and then locked into physical 
memory. (The disk driver is responsible for any memory management functions of this type.) The size of the 
transfer does not affect the applicable quotas (direct I/O count, buffered I/O count, and asynchronous system 
trap (AST) count limit). These quotas refer to the number of outstanding I/O operations of each type, not the 
size of the I/O operation being performed. 


The volume to which a logical or virtual function is directed must be mounted for the function actually to be 
executed. If it is not mounted, either a “device not mounted” or “invalid volume” status is returned in the I/O 
status block. 


Table 2-5 lists the logical, virtual, and physical disk I/O functions and their function codes. Chapter 1 
describes the QIO level interface to the disk device ACP. 


Table 2-5 Disk I/O Functions 
Function Code Arguments Type! Function Modifiers Function 
10$_ACCESS P1, [P2],[P3], V I0$M_CREATE Search a directory for a 
[P4], [P5] IO$M_ACCESS specified file and access the 
file if found. 
10$_ACPCONTROL P1,[P2],[P3], V 10$M_DMOUNT Perform miscellaneous 
[P4],[P5] control functions. 
10$_AVAILABLE Pp Clear volume valid; make 
DSA units available. 
10$_CREATE P1,[P2],[P3], V IO$M_CREATE Create a directory entry or 
[P4],[P5] I0$M_ACCESS a file. 
IO$M_DELETE 
10$_DEACCESS P1,[P2],[P3], V Deaccess a file and, if 
[P4],[P5] specified, write final 
attributes in the file 
header. 
10$_ DELETE P1,[P2],[P3],[ V IO$M_ DELETE Remove a directory entry 
P4],[P5] or file header, or both. 
10$_FORMAT Pl P Set density (RX02 only). 
10$_MODIFY P1,[P2],[P3], V Modify the file attributes 
[P4],[P5] or allocation, or both. 
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Table 2-5 Disk I/O Functions (Continued) 
Function Code Arguments Type! Function Modifiers Function 
I0$_PACKACK P Update UCB fields if RX02; 
initialize volume valid on 
other devices. Bring DSA 
units on line. 
10$_READLBL? P1,P2,P3 L IO$M_DATACHECK? Read logical block. 
IO$M_INHRETRY 

10$_READPBLK? P1,P2,P3 P IO$M_DATACHECK? Read physical block.® 
IO$M_INHRETRY 
I10$M_INHSEEK* 

10$_READVBLK? P1,P2,P3 Vv I0$M_DATACHECK? __ Read virtual block. 
IO$M_INHRETRY 

10$_SEARCH Pl P Search for specified block 
or sector (only for TU58). 

10$_SEEK Pl P Seek to specified cylinder.® 

IO0$_SENSECHAR P Sense the 
device-dependent 
characteristics and return 
them in the I/O status 
block. 

10$_SENSEMODE L Sense the 
device-dependent 
characteristics and return 
them in the I/O status 
block. 

I0$_SETPRFPATH Pl P I0$M_FORCEPTH Specifies a preferred path 
for DSA disks. 

IO$_ UNLOAD Pp Clear volume valid; make 
DSA units available and 
spin down the volume. 

10$_WRITECHECK 2 P1,P2,P3 P Verify data written to disk 
by a previous write QIO.? 

10$_WRITELBLK? P1,P2,P3 L I0$M_DATACHECK? Write logical block. 
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Table 2-5 Disk I/O Functions (Continued) 


Function Code Arguments Type! Function Modifiers Function 


10$_WRITEPBLK? P1,P2,P3 P 10$M_DATACHECK? Write physical block.° 


IO$M_ERASE 
IO0$M_INHRETRY 


10$M_INHSEEK* 
I0$M_DELDATA® 


10$_WRITEVBLK? P1,P2,P3 Vv IO$M_ DATACHECK? Write virtual block. 


IO$M_ERASE 
IO0$M_INHRETRY 


. V= virtual; L = logical; P = physical. 

. On OpenVMS Alpha, P1 supports a 64-bit address. 
. Not for RX01 and RX02 disks. 

. Not for TU58, TX01, RX02, RBO2 and RLO2 drives. 
. Not for DSA and SCSI disks. 

. RX02 only. 


aOorwhd ke 


The function-dependent arguments for IO$_CREATE, IO$_ACCESS, IO$_DEACCESS, IO$_MODIFY, and 
10$_DELETE are as follows: 


P1—tThe address of the file information block (FIB) descriptor. 


P2—The address of the file name string descriptor (optional). If specified, the name is entered in the 
directory specified by the FIB. 


P3—The address of the word that is to receive the length of the resulting file name string (optional). 
P4—The address of a descriptor for a buffer that is to receive the resulting file name string (optional). 


P5—The address of a list of attribute descriptors (optional). If specified, the indicated attributes are read 
(10$_ACCESS) or written (IO$_CREATE, IO$_DEACCESS, and IO$_MODIFY). 


See Chapter 1 for more information on these functions. 


The function-dependent arguments for IO$_READVBLK, IO$_READLBLK, IO$_WRITEVBLK, and 
IO$_WRITELBLK are as follows: 


P1—tThe starting virtual address of the buffer that is to receive the data from a read operation; or, in the 
case of a write operation, the virtual address of the buffer that is to be written on the disk. On OpenVMS 
Alpha, P1 can be a 64-bit address. 


P2—The number of bytes that are to be read from the disk, or written from memory to the disk. An even 
number must be specified if the controller is an RK611, RL11, RX211, or UDA5O. 


P3—The starting virtual/logical disk address of the data to be transferred in a read operation; or, in a 
write operation, the disk address of the area that is to receive the data. 


In a virtual read or write operation, the address is expressed as a block number within the file, that is, 
block 1 of the file is virtual block 1. (Virtual block numbers are converted to logical block numbers using 
mapping windows that are set up by the file system ACP process.) 


In a logical read or write operation, the address is expressed as a block number relative to the start of the 
disk. For example, the first sector on the disk contains block 0 (or at least the beginning of block 0). 
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The function-dependent arguments for IO$_WRITEVBLK, IO$_WRITELBLK, and I0$_WRITEPBLK 
functions that include the IO$M_ ERASE function modifier are as follows: 


P1——tThe starting virtual address of the buffer that contains a 4-byte, user-specified erase pattern. If the 
P1 address is 0, a longword of 0 will be used for the erase pattern. If the P1 address is nonzero, the 
contents of the 4 bytes starting at that address will be used as the erase pattern. Compaq recommends 
that the user specify a P1 address of 0 to lower system overhead. On OpenVMS Alpha, P1 can be a 64-bit 
address. 


NOTE DSA disk controllers provide controlled, assisted erasing for the IO$M_ERASE modifier 
(with virtual and logical write functions) only when the erase pattern is all zeros. If a 
nonzero erase pattern is used, there is a significant performance degradation with these 
disks. DSA disks do not accept physical QIO transfers. 


P2—The number of bytes of erase pattern to write to the disk. The number specified is rounded up to the 
next highest block boundary (512 bytes). 


P3—The starting virtual, logical, or physical disk address of the data to be erased. 


The function-dependent arguments for IO$_WRITECHECK, IO0$_READPBLK, and IO$_WRITEPBLK are as 
follows: 


P1—tThe starting virtual address of the buffer that is to receive the data in a read operation; or, in a write 
operation, the starting virtual address of the buffer that is to be written on the disk. Passed by reference. 
On OpenVMS Alpha and OpenVMS I64, P1 can be a 64-bit address. 


P2—The number of bytes that are to be read from the disk, or written from memory to the disk. Passed by 
value. An even number must be specified if the controller is an RK611, RL11, or UDA5O. 


P3—The starting physical disk address of the data to be read in a read operation; or, in a write operation, 
the starting physical address of the disk area that is to receive the data. Passed by value. The address is 
expressed as sector, track, and cylinder in the format shown in Figure 2-5. (On the RX01 and RX02, the 
high word specifies the track number rather than the cylinder number.) Check the UCB of a currently 
mounted device to determine the maximum physical address value for that type of device. 


NOTE On the RB80 and RM80, do not address cylinders 560 and 561. These two cylinders are 
used for diagnostic testing only. 


The function-dependent argument for IO$_SEARCH is as follows: 
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P1—The physical disk address where the tape is positioned. The address is expressed as sector, track, and 
cylinder in the format shown in Figure 2-5. 


Figure 2-5 Starting Physical Address 
31 16 15 8 7 0 


P3: Cylinder Track | Sector 


(Except RX01 and RX02) 


31 16 15 0 


(RX01 and RX02 Only) 


ZK0652GE 


The function-dependent argument for IO$_SEEK is as follows: 


P1—The physical cylinder number where the disk heads are positioned. The address is expressed in the 
format shown in Figure 2-6. 


Figure 2-6 Physical Cylinder Number Format 
31 16 15 0 


ZKO653GE 


The function-dependent argument for IO$_FORMAT is as follows: 
P1—tThe density at which an RX02 diskette is reformatted (see Section 2.4.4). 


2.4.1 Read 


The read function reads data into a specified buffer from disk starting at a specified disk address. 


The operating system provides the following read function codes: 


e IO$ READVBLK—Read virtual block 
¢ 10$_READLBLK—Read logical block 
e 10$_READPBLK—Read physical block 


If a read virtual block function is directed to a volume that is mounted foreign, that function is converted to 
read logical block. If a read virtual block function is directed to a volume that is mounted structured, the 
volume is handled in the same way as for a file-structured device. 


Three function-dependent arguments are used with these codes: P1, P2, and P3. These arguments are 
described in Section 2.4. 
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The data check function modifier (IO$M DATACHECK) can be used with all read functions. If this modifier 
is specified, a data check operation is performed after the read operation completes. A data check operation is 
also performed if the volume that has been read, or the volume on which the file resides (virtual read) has the 
characteristic “data check all reads.” Furthermore, a data check is performed after a virtual read if the file 
has the attribute “data check on read.” The RX01 and RX02 drivers do not support the data check function. 


If IO$M_DATACHECK is specified with a read function code to a TU58, or if the volume read has the 
characteristic “data check all reads,” a read check operation is performed. This alters certain TU58 hardware 
parameters when the tape is read. (The read threshold in the data recovery circuit is increased; if the tape 
has any weak spots, errors are detected.) 


The data check function modifier to a disk or tape can return five error codes in the I/O status block: 


SS$_CTRLERR SS$_DRVERR SS$_MEDOFL 
SS$_NONEXDRV SS$ NORMAL 


If no errors are detected, the disk or tape data is considered reliable. 


The inhibit retry function modifier (IO$M_INHRETRY) can be used with all read functions. If this modifier is 
specified, all error recovery attempts are inhibited. IO$M_INHRETRY takes precedence over 
IO$M_DATACHECK. If both are specified and an error occurs, there is no attempt at error recovery and no 
data check operation is performed. If an error does not occur, the data check operation is performed. 


2.4.2 Write 


The write function writes data from a specified buffer to disk starting at a specified disk address. 


The operating system provides the following write function codes: 


¢ 10$_WRITEVBLK—Write virtual block 
e 10$_WRITELBLK—Write logical block 
¢ I0$_WRITEPBLK—Write physical block 


If a write virtual block function is directed to a volume that is mounted foreign, the function is converted to 
write logical block. If a write virtual block function is directed to a volume that is mounted structured, the 
volume is handled in the same way as for a file-structured device. 


Three function-dependent arguments are used with these codes: P1, P2, and P3. These arguments are 
described in Section 2.4. 


The data check function modifier (IO$M_DATACHECK) can be used with all write operations. If this modifier 
is specified, a data check operation is performed after the write operation completes. A data check operation is 
also performed if the volume written, or the volume on which the file resides (virtual write), has the 
characteristic “data check all writes.” Furthermore, a data check is performed after a virtual write if the file 
has the attribute “data check on write.” The RX01 and RX02 drivers do not support the data check function. 


If IO$M_DATACHECK is specified with a write function code to a TU58, or if the volume written has the 
characteristic “data check all writes,” a write check operation is performed. The write check verifies data 
written on the tape. First, the specified data is written on the tape. Then the tape is reversed and the TU58 
controller reads the data internally to perform a checksum verification. If the checksum verification is 
unsuccessful after eight attempts, the write check operation is aborted and an error status is returned. 
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The inhibit retry function modifier (IO$M_INHRETRY) can be used with all write functions. If that modifier 
is specified, all error recovery attempts are inhibited. IO$M_INHRETRY takes precedence over 
IO$M_DATACHECK. If both IO$M_INHRETRY and IO$M_DATACHECK are specified and an error occurs, 
there is no attempt at error recovery, and no data check operation is performed. If an error does not occur, the 
data check operation is performed. IO$M_INHRETRY has no effect on DSA disks. 


The write deleted data function modifier (IO$M_DELDATA) can be used with the write physical block 
(I10$_WRITEPBLK) function to the RX02. If this modifier is specified, a deleted data address mark instead of 
the standard data address mark is written preceding the data. Otherwise, the operation of the 
I0$_WRITEPBLK function is the same; write data is transferred to the disk. When a successful read 
operation is performed on this data, the status code SS$_RDDELDATA is returned in the I/O status block 
rather than the usual SS$ NORMAL status code. 


The IO$M_ERASE function modifier can be used with all write function codes to erase a user-selected part of 
a disk. This modifier propagates an erase pattern through the specified range. Section 2.4 describes the write 
function arguments to be used with IO$M_ERASE. 


2.4.3 Sense Mode 


Sense mode operations obtain current disk device-dependent characteristics that are returned to the caller in 
the second longword of the I/O status block (see Figure 2-8). The operating system provides the following 
function codes: 


e I0$ SENSEMODE—Sense characteristics 
e I0$ SENSECHAR—Sense characteristics 


I0$_SENSEMODE is a logical function. IO$_SENSECHAR is a physical I/O function and requires the access 
privilege necessary to perform physical I/O. No device- or function-dependent arguments are used with either 
function. 


2.4.4 Set Density 


The set density function assigns a new density to an entire RX02 diskette. The diskette is also reformatted: 
new data address marks are written (single or double density) and all data fields are zeroed. Set density is a 
physical I/O function and requires the access privilege necessary to perform physical I/O. The following 
function code is provided: 


10$_FORMAT 
I0$_FORMAT takes the following function-dependent argument: 
P1—tThe density at which the diskette is reformatted: 
0 = single density (default) 
1 = single density 
2 = double density 


The set density operation should not be interrupted before it is completed (about 15 seconds). If the operation 
is interrupted, the resulting diskette might contain illegal data address marks in both densities. The diskette 
must then be completely reformatted and the function reissued. 
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2.4.5 Search 


The search function positions a TU58 magnetic tape to the block specified. Search is a physical I/O function 
and requires the access privilege necessary to perform physical I/O. The operating system provides a single 
function code: 


10$_SEARCH 


This function code takes the following function-dependent argument: 


P1—Specifies the block where the read/write head will be positioned. The low byte contains the sector 
number in the range 0 to 127; the high byte contains the track number in the range 0 to 3. 


I0$_SEARCH can save time between read and write operations. For example, nearly 30 seconds are required 
to completely rewind a tape. If the last read or write operation is near the end of the tape and the next 
operation is near the beginning of the tape, the search operation can begin after the last operation completes, 
and the tape will rewind while the process is otherwise occupied. (The search QIO is not completed until the 
search is completed. Consequently, if a $QIOW system service request is issued, the process will be held up 
until the search is completed.) 


2.4.66 Pack Acknowledge 


The pack acknowledge function sets the volume valid bit for all disk devices. Pack acknowledge is a physical 
I/O function and requires the access privilege to perform physical I/O. If directed to an RX02 disk, pack 
acknowledge also determines the diskette density and updates the device-dependent information returned by 
$GETDVI item codes DVI$_CYLINDERS, DVI$_TRACKS, DVI$_SECTORS, DVI$_DEVTYPE, 
DVI$_CLASS, and DVI$_MAXBLOCK. If directed to a DSA disk, pack acknowledge also sends the online 
packet to the controller. The following function code is provided: 


I0$_PACKACK 
This function code takes no function-dependent arguments. 


I0$_PACKACK must be the first function issued when a volume (pack, cartridge, or diskette) is placed in a 
disk drive. IO$_PACKACK is issued automatically when the DCL commands INITIALIZE or MOUNT are 
issued. 


For DSA disks, the IO$_PACKACK function locks the drive's port selector on the port that initiated the pack 
acknowledge function. 


In addition, the IO$_PACKACK function updates device-dependent information about DSA disks returned by 
$GETDVI. 


2.4.7 Unload 


The unload function clears the volume valid bit for all disk drives, makes DSA disks available, and issues an 
unload command to the drive (spins down the volume). The unload function reverses the function performed 
by pack acknowledge (see Section 2.4.6). The following function code is provided: 


10$_UNLOAD 


This function takes no function-dependent arguments. 


2.4.8 Available 


The available function clears the volume valid bit for all disk drives; that is, it reverses the function 
performed by pack acknowledge (see Section 2.4.6). No unload function is issued to the drive; therefore, those 
drives capable of spinning down do not spin down. The following function code is provided: 
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10$_AVAILABLE 


This function takes no function-dependent arguments. 


2.4.9 Seek 


The seek function directs the read/write heads to move to the cylinder specified in the P1 argument (see 
Sections Section 2.2.8, Section 2.4, and Figure 2-6). 


2.4.10 Write Check 


The write check function verifies that data was written to disk correctly. The data to be checked is addressed 
using physical disk addressing (sector, track, and cylinder) (see Figure 2-5). If the request is directed toa DSA 
disk, you must specify a logical block number, even though I0$_WRITECHECK is a physical I/O function. 
The following function code is provided: 


10$_WRITECHECK 


A write QIO must be used to write data to disk before you enter this command. IO$_WRITECHECK then 
reads the same block of data and compares it with the data in the specified buffer. Three function-dependent 
arguments are used with this code: P1, P2, and P3. These arguments are described in Section 2.4. 


I0$_WRITECHECK is similar to the IO$M_DATACHECK function modifier for write QIOs, except that 
IO0$_WRITECHECK does not write the data to disk; it is specified after data is written by a separate write 
QIO. Nonprivileged processes can use the IO$M_DATACHECK modifier with IO$_WRITEVBLK (which does 
not require access privilege) to determine whether data is written correctly. The RX01 and RX02 drivers do 
not support the write check function. 


The write check function and the data check function modifier to a TU58 can return six error codes in the I/O 
status block: SS$_ NORMAL, SS$_CTRLERR, SS$_DRVERR, SS$_MEDOFL, SS$_NONEXDRY, and 
SS$_WRTLCK. 


2.4.11 Set Preferred Path 


The set preferred path function specifies a preferred path for DSA disks. This includes RA-series disks and 
disks accessed through the MSCP server. If a preferred path is specified for a disk, the MSCP disk class 
drivers (DUDRIVER and DSDRIVER) use the path as their first attempt to locate the disk and bring it on 
line as a result of a DCL command MOUNT or failover of an already mounted disk. 


In addition, you can initiate failover of a mounted disk to force the disk to the preferred path, or to use 
load-balancing information for disks accessed through MSCP servers. 


The function code is: 


10$_SETPRFPATH 


The following is the function modifier: 


I0$M_FORCEPATH—Causes the disk class driver to select the server path with the highest load 
available rating. 


The P1 parameter contains the address of a counted ASCII string (.ASCIC). This string is the node name of 
the HSC or system that is the preferred path. The node name must match an existing node that is known to 
the local node and if the node is a VAX or Alpha system, it must be running the MSCP server. This function 
does not move the disk to the preferred path. 


The PHYS_IO privilege is required for IO$_SETPRFPATH and IO$M_FORCEPATH. 
The following example shows the use of IO$_SETPRFPATH: 
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Sassigndef 
Sqiodef 
Siodef 
Sexitdef 
dev: -ascid /$254SDUA48:/ 
chnl: .word 0 
node: -ascic /HSCO001/ 


-entry start,0 


Sassign_s devnam=dev, - 
chan=chnl 

blbc r0,done 

Sqiow_s chan=chn1, - 
func=#10S$_SETPRFPATH, - 
pl=node 


done: 
Sexit_s r0 
-end start 


This updates the local node I/O database to indicate that node HSC001 is the preferred path for DUA48. 


2.4.11.1 Forcing a Path Change 


You can move a disk that is already mounted to its preferred path by specifying the IO$M_FORCEPATH 
modifier. If a preferred path has not been specified for a disk that is accessed through the MSCP server, the 
IO$M_FORCEPATH function causes the disk class driver to use load-balancing information to select the 
server path with the highest-load-available rating. 


IO$M_FORCEPATH does not accept any arguments. If you intend to move a disk to its preferred path, you 
must specify the preferred path in a separate $QIO function. 


The following example shows a use of the IO$M_FORCEPATH function modifier: 
Sassigndef 
Sqiodef 
Siodef 
Sexitdef 
dev: -ascid /$254SDUA197:/ 
chnl: -word 0 
-entry start,0 
Sassign_s devnam=dev, - 


chan=chnl 
blbc r0,done 
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Sqiow_s chan=chnl,- 
func=#$_SETPRFPATH! IOSM_FORCEPATH> 


done: 
Sexit_s r0 
.end start 


Note that forcing a path change places the disk in mount verification. New I/O requests are suspended until 
mount verification is complete. 


2.4.11.2 Using I0$_SETPRFPATH with Disks Dual-Pathed Between HSCs 


You can use the IO$¢_ SETPRFPATH and IO$¢M_FORCEPATH functions to load balance disks that are 
dual-pathed between HSCs. The IO$M_FORCEPATH function initiates failover of the disk on all nodes that 
have it mounted and that have a direct path to the HSCs. Because the node that issues the 
IO0$M_FORCEPATH might not be the first one to attempt failover of the disk, it is essential that all nodes 
with direct connections to the HSCs specify the same preferred path for the disk. Only one node should issue 
the IO$M_FORCEPATH request. 


2.4.11.3 Using I0$_SETPRFPATH with Disks Dual-Pathed Between Systems 


You can use IO$M_FORCEPATH to load balance RA-series disks that are dual-pathed between systems 
running the MSCP server. Both serving nodes should specify the same preferred path. To move the disk 
between systems, the system that currently has the disk on line through its local controller should issue the 
IO$M_FORCEPATH request. The disk must be mounted on both serving nodes. 

2.4.11.4 Using I10$_SETPRFPATH with Disks Accessed Through MSCP Servers 


You can specify a preferred path for disks that are accessed through MSCP servers; however, this 
specification overrides any load-balancing decisions. 


Note that if a disk can be accessed through both HSC and MSCP servers, you need not specify the HSC as a 
preferred path. HSC paths are always preferred to server paths. 


Using IO$M_FORCEPATH without a preferred path causes the disk class driver to move the disk to the 
server with the highest available capacity. 


2.4.11.5 Using 10$_SETPRFPATH with Phase I Volume Shadowing 


You can specify IO$_SETPRFPATH for shadow set members, but not for virtual units. IO$M_FORCEPATH is 
not supported for shadow set members or virtual units. 


2.4.11.6 Using I0$_SETPRFPATH with Phase II Volume Shadowing 
10$_SETPRFPATH and IO$M_FORCEPATH are supported for shadow set members but not for virtual units. 
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2.5 VO Status Block 


Figure 2-7 shows the I/O status block (IOSB) for all disk device QIO functions except sense mode. Figure 2-8 
shows the I/O status block for the sense mode function. Figure 2-8 lists the status messages for all functions 
and devices. (The OpenVMS system messages documentation provides explanations and suggested user 
actions for these messages. ) 


Figure 2-7 IOSB Contents 
31 16 15 0 


Byte Count 
(LowOrder Word) Status 


Byte Count 
(HighOrder Word) 
ZKO656GE 


The byte count is a 32-bit integer that gives the actual number of bytes transferred to or from the process 
buffer. 


Figure 2-8 IOSB Contents for the Sense Mode Function 
31 16 15 8 7 0 


ee 


ZK0657GE 


The second longword of the I/O status block for the sense mode function returns information about the 
cylinder, track, and sector configurations for the particular device. 


2.6 Disk Driver Programming Example 


A sample VAX MACRO disk driver program, DISK_DRIVER.MAR, is shown in Example 2-1. This sample 
program provides an example of optimizing access time to a disk file. The program creates a file using Record 
Management Services (RMS), stores information concerning the file, and closes the file. The program then 
accesses the file and reads and writes to the file using the Queue I/O ($QIO) system service. 


Example 2-1 DISK_DRIVER.MAR Disk Driver Programming Example 


: KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK 


-TITLE Disk Driver Programming Example 
.-IDENT /01/ 
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; Define necessary symbols. 


SFIBDEF ;Define file information block Offsets 
SIODEF ;Define I/O function codes 
SRMSDEF ;Define RMS-32 Return Status Values 


; Local storage 


; Define number of records to be processed. 


NUM_RECS=100 ;One hundred records 


; Allocate storage for necessary data structures. 


; Allocate File Access Block. 


; A file access block is required by RMS-32 to open and close a 
: file. 
r 
FAB_BLOCK: r 
SFAB ALQ = 100,- ;Initial file size is to be 
= 7100 blocks 
FAC = PUT,- ;File Access Type is output 
FNA = FILE_NAME, - ;File name string address 
FNS = FILE_SIZE,- ;File name string size 
FOP = CTG,- 7File is to be contiguous 
MRS = 512,- ;Maximum record size is 512 
= ;bytes 
NAM = NAM_BLOCK, - ;File name block address 
ORG = SEQ,- 7;File organization is to be 
= ; sequential 
REM = FIX ;Record format is fixed length 


; Allocate file information block. 


; A file information block is required as an argument in the 
; Queue I/O system service call that accesses a file. 

, 

FIB_ BLOCK: i 


. BLKB FIBSK_LENGTH ; 


, 
; Allocate file information block descriptor. 


, 


FIB_DESCR: ; 
. LONG FIBSK_LENGTH ;Length of the file 
;information block 
. LONG FIB_BLOCK ;Address of the file 


;information block 
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; Allocate File Name Block 


; A file name block is required by RMS-32 to return information 
; concerning a file (for example, the resultant file name string 
H after logical name translation and defaults have been applied). 
, 
NAM_BLOCK: i 

SNAM ; 


; Allocate Record Access Block 


; A record access block is required by RMS-32 for record 
; operations ona file. 
, 
RAB_BLOCK: 
SRAB FAB = FAB_BLOCK, - ;File access block address 
RAC = SEQ,- ;Record access is to be 
= 7 sequential 
RBF = RECORD_BUFFER, - ;Record buffer address 
RSZ = 512 ;Record buffer size 


, 
; Allocate direct address buffer 


, 


BLOCK_BUFFER: 
. BLKB 1024 ;Direct access buffer is 1024 
;bytes 


, 
; Allocate space to store channel number returned by the SASSIGN 
; Channel system service. 
, 
DEVICE_CHANNEL: 7 
. BLKW 1 ; 


, 
; Allocate device name string and descriptor. 


r 


DEVICE_DESCR: ; 


. LONG 20$-10$ ;Length of device name string 
. LONG 10$ ;Address of device name string 
10S: -ASCII /SYSSDISK/ ;Device on which created file 
;will reside 
20S: ;Reference label to calculate 
; length 


; Allocate file name string and define string length symbol. 


FILE_NAME: ; 
-ASCII /SYSSDISK:MYDATAFIL.DAT/ ;File name string 


FILE_SIZE=.-—-FILE_NAME ;File name string length 
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, 
; Allocate I/O status quadword storage. 


a 


IO_STATUS: i 
- BLKQ 1 i 


; Allocate output record buffer. 


RECORD_BUFFER: ; 
. BLKB 512 7Record buffer is 512 bytes 


KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK 


i Start Program 


KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK 


; The purpose of the program is to create a file called MYDATAFIL.DAT 
7 using RMS-32; store information concerning the file; write 100 

; records, each containing its record number in every byte; 

; close the file; and then access, read, and write the file directly, 
; using the Queue I/O system service. If any errors are detected, the 
7 program returns to its caller with the final error status in 

; register RO. 


-ENTRY DISK_EXAMPLE,“*M,R3,R4,R5,R6> ;Program starting 
j;address 


; First create the file and open it, using RMS-32. 


, 


PART_1: ;First part of example 
SCREATE FAB = FAB_BLOCK ;Create and open file 
BLBC RO,20$ ;If low bit = 0, creation 
;failure 


; Second, connect the record access block to the created file. 


SCONNECT RAB = RAB BLOCK ;Connect the record access 
; block 

BLBC RO, 30$ ;If low bit = 0, creation 
;failure 


; Now write 100 records, each containing its record number. 


MOVZBL #NUM_RECS,R6 7Set record write loop count 
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, 


; Fill each byte of the record to be written with its record number. 


, 


10S: 


SUBB3 R6, #NUM_RECS+1,R5 ;Calculate record number 


MOVC5 #0, (R6),R5,#512,RECORD_BUFFER ;Fill record buffer 


; Now use RMS-32 to write the record into the newly created file. 


SPUT RAB = RAB BLOCK ;Put record in file 
BLBC RO, 30$ ;If low bit = 0, put failure 
SOBGTR R6,10S ;Any more records to write? 


; The file creation part of the example is almost complete. All that 
; remains to be done is to store the file information returned by 
; RMS-32 and close the file. 


20$ 


a 


MOVW NAM_BLOCK+NAMSW_FID, FIB_BLOCK+FIBSW_FID ;Save file 
; identification 

MOVW NAM_BLOCK+NAMSW_FID+2,FIB_BLOCK+FIBSW_FID+2 ; Save 
; sequence number 

MOVW NAM_BLOCK+NAMSW_FID+4,FIB_BLOCK+FIBSW_FID+4 ; Save 
;relative volum 

SCLOSE FAB = FAB _BLOCK ;Close file 

BLBS RO,PART_2 ;If low bit set, successful 
;close 

RET ;Return with RMS error status 


; Record stream connection or put record failure. 


, 


; Close file and return status. 


30S: 


PUSHL RO ;Save error status 

SCLOSE FAB = FAB_BLOCK ;Close file 

POPL RO ;Retrieve error status 

RET ;Return with RMS error status 


; The second part of the example illustrates accessing the previously 
; created file directly using the Queue I/O system service, randomly 
; veading and writing various parts of the file, and then deaccessing 
; the file. 


; First, 


; file. 
PART_2: 
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SASSIGN_S DEVNAM = DEVICE_DESCR,- ;Assign a channel to file 
CHAN = DEVICE_CHANNEL ; device 
BLBC RO,20$ 7If low bit = 0, assign 
;failure 
MOVL #FIBSM NOWRITE!FIBSM _WRITE,- ;Set for read/write 
FIB_BLOCK+FIB$L_ACCTL jaccess 
SQIOW_S CHAN = DEVICE_CHANNEL,- ;Access file on device channel 
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ty 
G 
a 
Q 
ll 


#IO$S_ACCESS!IOSM_ACCESS,- ;1I/0 function is 
= j;access file 
IO_STATUS, - j;Address of I/O status 
= 7 Quadword 
Pl = FIB_DESCR ;Address of information block 
;descriptor 
BLBC RO,10$ ;If low bit = 0, access 
;failure 
MOVZWL IO_STATUS, RO ;Get final I/O completion 
;status 


H 
[e) 
n 
w 
ll 


BLBS RO, 30$ ;If low bit set, successful 
;I1/O function 


10S: PUSHL RO ;Save error status 


SDASSGN_S CHAN = DEVICE_CHANNEL ;Deassign file device channel 
POPL RO ;Retrieve error status 


208: RET ;Return with I/O error status 


a 
, 
, 
, 
, 


, 


The file is now ready to be read and written randomly. Since the 
records are fixed length and exactly one block long, the record 
number corresponds to the virtual block number of the record in the 
file. Thus a particular record can be read or written simply by 
specifying its record number in the file. 


The following code reads two records at a time and checks to see 
that they contain their respective record numbers in every byte. 
The records are then written back into the file in reverse order. 
This results in record 1 having the old contents of record 2 and 
record 2 having the old contents of record 1, and so forth. After 
the example has been run, it is suggested that the file dump 
utility be used to verify the change in data positioning. 


30S MOVZBL #1,R6 7Set starting record (block) 


, 


;number 


Read next two records into block buffer. 


40S: SQTO_S CHAN = DEVICE_CHANNEL,- ;Read next two records from 
= ;file channel 
FUNC = #I10S_READVBLK,- ;1/0 function is read virtual 
= *block 
IOSB = IO_STATUS,- ;Address of I/O status 
= 7 Quadword 
P1 = BLOCK_BUFFER, -— ;Address of I/O buffer 
P2 = #1024,- ;Size of I/O buffer 
P3 = R6 ;Starting virtual block of 
;transfer 
BSBB 50S ;Check I/O completion status 


, 
a 


, 


Check each record to make sure it contains the correct data. 


SKPC R6, #512, BLOCK_BUFFER ;Skip over equal record 
;numbers in data 
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BNEQ 60$ ;If not equal, data match 
;failure 

ADDL3 #1,R6,R5 ;Calculate even record number 

SKPC R5,#512,BLOCK_BUFFER+512 ;Skip over equal record 
;numbers in data 

BNEQ 60$ 7If not equal, data match 
;failure 


; Record data matches. 


; Write records in reverse order in file. 
v 
SQIOW_S CHAN = DEVICE_CHANNEL,- ;Write even-numbered record in 
= ;odd slot 
FUNC = #I10S_WRITEVBLK,- ;1I/O function is write virtual 
= ; block 
IOSB = IO_STATUS,- ;Address of I/O status 
= 7 Quadword 
Pl = BLOCK_BUFFER+512,- ;Address of even record buffer 
P2 = #512,- ;Length of even record buffer 
P3 = R6 ;Record number of odd record 
BSBB 50S ;Check I/O completion status 
ADDL3 #1,R6,R5 ;Calculate even record number 
SQIOW_S CHAN = DEVICE_CHANNEL,- ;Write odd numbered record in 
= ;even slot 
FUNC = #10S_WRITEVBLK,- ;1I/O function is write virtual 
= ; block 
IOSB = IO_STATUS,- ;Address of I/O status 
= 7 Quadword 
Pl = BLOCK_BUFFER, -— ;Address of odd record buffer 
P2 = #512,- ;Length of odd record buffer 
P3 = RS ;Record number of even record 
BSBB 50S ;Check I/O completion status 
ACBB #NUM_RECS-1, #2,R6,40$ ;Any more records to be read? 
BRB 70$ r 
, 
; Check I/O completion status. 
, 
50$ BLBC RO, 70$ ; If low bit = 0, service 
;failure 
MOVZWL IO_STATUS, RO ;Get final I/O completion 
;status 
BLBC RO, 70S ;If low bit = 0, I/O function 
RSB ; failure 
, 
; Record number mismatch in data. 
v 
60S: MNEGL #4, RO ;Set dummy error status value 
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, 
; All records have been read, verified, and odd/even pairs inverted 


, 


70S: PUSHL RO ;Save final status 
SQIOW_S CHAN = DEVICE_CHANNEL,- ;Deaccess file 
FUNC = #I0S_DEACCESS ;1/O function is deaccess file 
SDASSGN_S CHAN = DEVICE_CHANNEL ;Deassign file device channel 
POPL RO ;Retrieve final status 
RET r 
. END DISK_EXAMPLE 
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3 Magnetic Tape Drivers 


This chapter describes the use of magnetic tape drivers, drives, and controllers. 


3.1 HP Magnetic Tape Controllers and Drives 


The following sections describe magnetic tape controllers and drives; however, note that not all supported 
devices are described here. Refer to the Software Product Description for the OpenVMS Operating System 
(SPD 82.35.xx) for the definitive list of supported devices. 


3.1.1 TM03 Magnetic Tape Controller (VAX Only) 


On VAX systems, the TM03 magnetic tape controller supports up to eight TE16, TU45, or TU77 tape drives. 
These dual-density (800 or 1600 bit/inch) drives differ in speed: the TE16, TU45, and TU77 read and write 
data at 45, 75, and 125 inches per second (ips), respectively. Each drive can hold one 2400-foot, 9-track reel 
with a capacity of approximately 40 million characters. The TM03 controller is connected to the MASSBUS 
through a MASSBUS adapter. 


3.1.2 TS11 Magnetic Tape Controller (VAX Only) 


On VAX systems, the TS11 magnetic tape controller connects to the UNIBUS through a UNIBUS adapter and 
supports one TS04 tape drive. The TS11/TS04 is a single-density tape system that supports 1600-bit/inch, 
phase-encoded recording. 


The TSU05 and the TSV05 magnetic tape drives are used with UNIBUS and Q-bus systems, respectively. 


3.1.3  TM78 and TM79 Magnetic Tape Controllers (VAX Only) 


On VAX systems, the TM78 and TM79 magnetic tape controllers support up to four TU78 tape drives. These 
high-performance, dual-density drives (1600 or 6250 bit/inch) operate at 125 ips using a 2400-foot reel of tape 
with a capacity of approximately 146 million characters when recorded in the GCR (6250 bit/inch) mode. The 
TM78 and TM79 controllers are connected to the MASSBUS through a MASSBUS adapter. 


3.1.4 TU80 Magnetic Tape Subsystem (VAX Only) 


On VAX systems, the TU80 is a single-density, dual-speed (25 or 100 ips) magnetic tape subsystem that uses 
streaming tape technology (see Section 3.2.7). It supports one drive per subsystem. The TU80 connects to the 
UNIBUS through a UNIBUS adapter and completely emulates the TS11 magnetic tape controller. 


3.1.5 TA81 Magnetic Tape Subsystem 


On VAX and Alpha systems, the TA81 is a high-performance, dual-density (1600 or 6250 bit/inch), dual-speed 
(25 or 75 ips) magnetic tape subsystem that uses streaming tape technology (see Section 3.2.7). It attaches to 
an HSC50 controller, and is managed with the TMSCP control protocol for tape mass storage. 
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3.1.6 TU81 Magnetic Tape Subsystem (VAX Only) 


On VAX systems, the TU81 is a high-performance, dual-density (1600 or 6250 bit/inch), dual-speed (25 or 75 
in/s) magnetic tape subsystem that uses streaming tape technology (see Section 3.2.7). It connects to the 
UNIBUS through a UNIBUS adapter, and is managed with the TMSCP control protocol for tape mass 
storage. 


3.1.7 TU81-Plus Magnetic Tape Subsystem (VAX Only) 


On VAX systems, the TU81-Plus is an enhanced version of the TU81 streaming tape subsystem. It is a 
9-track, dual-speed, dual-density, ANSI-standard, half-inch magnetic tape subsystem. In addition, it has a 
256-KB cache buffer that temporarily stores commands and data moving to and from the tape unit. The 
buffer increases the amount of time the tape drive is able to stream, thereby increasing performance. The 
TU81-Plus connects to all VAXBI, UNIBUS, and Q-bus systems using the KLESI-B, KLESI-U, and KLESI-Q 
adapters. 


3.1.8 TA90 Magnetic Tape Subsystem 


On VAX and Alpha systems, the TA90 is a 5- by 4-inch, 200-MB cartridge tape, fully read- and 
write-compatible with the IBM 3480 format. The TA90 includes a master controller and a dual transport unit. 
As many as three additional dual transport slave units can be connected to a single TA90 master controller 
for a total of eight drives. The controller connects to the HSC 5X-DA high-speed channel card in the HSC. 


TA90 tape drives can be equipped with optional stack loaders for unattended backup operations. Each TA90 
master has two dual-port STI connections to the HSC. Such dual pathing allows each control unit to service 
two HSC controllers, which significantly increases tape drive availability. The TA90 subsystem includes a 
2-MB cache that allows the controller to prefetch upcoming commands and store them while completing 
current data transfers. This behavior helps optimize performance. The TA90 is a TMSCP device. 


3.1.9 RV20 Write-Once Optical Drive (VAX Only) 


On VAX systems, the RV20, a 2 GB, double-sided, write-once optical (WORM) disk drive, is accessed 
sequentially similar to a tape. A 100-bit error correction code (ECC) protects user data. The controller 
performs bad block replacement. Three RV20 slaves can be daisy-chained to the subsystem controller in the 
RV20 master for a total of four drives. 


RV02 cartridges can be used on any HP RV20 optical subsystem. 


The average access time is 212.5 ms with an average seek rate of 150 ms. The maximum data transfer rate is 
262 KB per second (formatted and sustained) with a burst rate of 1.33 MB per second. 


3.1.10 TK50 Cartridge Tape System (VAX Only) 


On VAX systems, the TK50 is a 95-MB, 5.25-inch cartridge tape system that uses streaming tape technology 
(see Section 3.2.7). The TK50 records data serially on 22 tracks using serpentine recording, rather than on 
separate (parallel) tracks. Data written to tape is automatically read as it is written. A cyclic redundancy 
check (CRC) is performed and the controller is notified immediately if an error occurs on the tape. 


The TQK50 is a dual-height Q-bus controller for the TK50 tape drive. The TUK50 is a UNIBUS controller for 
the same drive. The TZK50 is a SCSI controller for the TK50 tape. Both the TQK50 and the TUK50 are 
TMSCP devices. 


Section 3.1.13 describes compatibility among the TK50, TK70, and TZ30 magnetic cartridge tape systems. 
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3.1.11 TK70 Cartridge Tape System (VAX Only) 


On VAX systems, the TK70 is a 295-MB, 5.25-inch, streaming cartridge tape system. (See Section 3.2.7 for 
information about streaming tape technology.) The TK70 tape drive records data serially on 48 tracks using 
serpentine recording, rather than separate (parallel) tracks. Data written to the tape is automatically read as 
it is written. A CRC check is performed and the controller is notified immediately if an error occurs on the 
tape. 

The TQK70 is a dual-height, Q-bus controller for the TK70 magnetic tape drive. The TK70 subsystem 
includes a 38-KB cache to optimize performance. The TBK70 is a VAXBI-bus controller for the same drive. 
Section 3.1.13 describes compatibility between the TK50 and TK70 magnetic cartridge tape systems. 


3.1.12 TZ30 Cartridge Tape System 


On VAX and Alpha systems, the TZ30 is a 95-MB, 5.25-inch, half-height cartridge streaming tape drive with 
an embedded SCSI controller. See Section 3.2.7 for information about streaming tape technology. The TZ30 
uses TK50 cartridge tapes. It records data serially on 22 tracks using serpentine recording, rather than 
separate parallel tracks. Section 3.1.13 describes compatibility between the TK50, TK70, and TZ30 magnetic 
cartridge tape systems. 


3.1.13 Read and Write Compatibility Between Cartridge Tape Systems 


When you insert a cartridge tape into the TZ30, TK50, and TK70 tape drives, the hardware initializes the 
media to a device-specific recording density automatically. 


Depending on the type of cartridge and the type of drive on which it is formatted (inserted and initialized), 
full read and write access to tape cartridges may not be permitted. 


Formatting a Blank TK50 Cartridge Tape 


A blank, unformatted TK50 cartridge can be formatted on the TK50, TK70, and TZ30 cartridge systems. For 
example, a TK70 tape drive has full read and write access to a TK50 cartridge formatted on a TK70 drive. 
Once the cartridge tape is formatted on a particular tape drive, the tape drive has full read and write access 
to the cartridge tape. 


Formatting a Previously Initialized TK50 Cartridge Tape 


If a TK50 cartridge tape is formatted on a TZ30 or TK50 cartridge tape drive, the TZ30 and TK50 drives 
initialize the TK50 cartridge to TK50 density. The following table summarizes the types of access available: 


TK50 


Controller Read Write 


T7301 Yes Yes 


TQK50 Yes Yes 
TQK70 Yes No 


1. Has an internal controller. 


The TK70 tape drive can read data on a TK50 cartridge formatted on a TK50 or TZ30 tape drive. 
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3.1.13.1 Formatting a TK50 or TK52 Cartridge Tape on a TK70 Tape Drive 


If a TK50 or TK52 cartridge tape is formatted on a TK70 tape drive, the TK70 cartridge tape drive initializes 
the TK50 or TK52 cartridge tape to TK70 density. The following table summarizes the types of access 
available: 


TK50 TK52 
Controller Read Write Read Write 
T7301 No No No No 
TQK50 No No No No 
TQK70 Yes Yes Yes Yes 


1. Has an internal controller. 


The TK50 and TZ30 tape drives cannot read or write data on a TK50 cartridge tape formatted on a TK70 
drive. 


3.2 Driver Features 
The magnetic tape drivers provide the following features: 


e Multiple master adapters and slave formatters 


e Different types of devices on a single MASSBUS adapter; for example, an RPO5 disk and a TM03 tape 
formatter 


e Reverse read function (except for the TZ30 and TK50 on TUK50 and TQK50 controllers) 
e Reverse data check function (except for the TZ30, TS11, and TK50 on TUK50 and TQK50 controllers) 
e Data checks on a per-request, per-file, or per-volume basis (except for the TS11) 


e Full recovery from power failure for online drives with volumes mounted, including repositioning by the 
driver (except on VAXstation 2000 and MicroVAX 2000 systems) 


e Extensive error-recovery algorithms; for example, nonreturn-to-zero-inverted (NRZI) error correction 
e Logging of device errors in a file that may be displayed by field service or customer personnel 
e Online diagnostic support for drive-level diagnostics 


The following sections describe master and slave controllers, and data check and error recovery capabilities in 
greater detail. 


3.2.1 Dual-Path HSC Tape Drives 


A dual-path HSC tape drive is a drive that connects to two HSCs, both of which have the same nonzero tape 
allocation class. The operating system recognizes the dual-pathed capability of such a tape drive under the 
following circumstances: (1) the operating system has access to both HSCs and (2) select buttons for both 
ports are depressed on the tape drive. 
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If one port fails, the operating system switches access to the operational port automatically, provided that the 
allocation class information has been defined correctly. 


3.2.2. Dynamic Failover and Mount Verification 


Dynamic failover occurs on dual-pathed tape drives if mount verification is unable to recover on the current 
path and an alternate path is available. The failover occurs automatically and transparently and then mount 
verification proceeds. 


A device enters mount verification when an I/O request fails because the device has become inoperative. This 
might occur in the following instances: 


e The device is accidentally placed off line. 

e The active port of an HSC-connected drive fails. 

e A hardware error occurs. 

e The device is set to write protected during a write operation. 


When the device comes back on line, either through automatic failover or operator intervention, the operating 
system validates the volume, restores the tape to the position when the I/O failure occurred, and retries the 
failed request. 


3.2.3 Tape Caching 


The RV20, TA90, TK70, and TU81-Plus contain write-back volatile caches. The host enables write-back 
volatile caches explicitly, either on a per-unit basis or on a per-command basis. To enable caching on a per-unit 
basis, enter the DCL MOUNT command specifying the qualifier /CACHE=TAPE_ DATA. 


The Backup utility enables caching on a per-command basis. The user can implement caching on a 
per-command basis at the QIO level by using the IO$M_NOWAIT function modifiers on commands where it is 
legal (see Table 3-4). In the unlikely event that cached data is lost, the system returns a fatal error and the 
device accepts no further I/O requests. Use the IO$M_FLUSH function code to ensure that all 
write-back-cached data is written out to the specified tape unit. The IO$_PACKACK, IO$_UNLOAD, 
10$_REWINDOFF, and IO$_AVAILABLE function codes also flush the cache. 


3.2.4 Master Adapters and Slave Formatters 


The operating system supports the use of many master adapters of the same type on a system. For example, 
more than one MASSBUS adapter (MBA) can be used on the same system. A master adapter is a device 
controller capable of performing and synchronizing data transfers between memory and one or more slave 
formatters. 


The operating system also supports the use of multiple slave formatters per master adapter on a system. For 
example, more than one TM03 or TM78 magnetic tape formatter per MBA can be used on a system. A slave 
formatter accepts data and commands from a master adapter and directs the operation of one or more slave 
drives. The TM03 and the TM78 are slave formatters. The TE16, TU45, TU77, and TU78 magnetic tape 
drives are slave drives. 
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3.2.5 Data Check 


After successful completion of an I/O operation, a data check is made to compare the data in memory with 
that on the tape. After a write or read (forward) operation, the tape drive spaces backward and then performs 
a write-check data operation. After a read operation in the reverse direction, the tape drive spaces forward 
and then performs a write-check data reverse operation. With the exception of TS04 and TU80 drives, 
magnetic tape drivers support data checks at the following three levels: 


e Per request—You can specify the data-check function modifier (IO$M_DATACHECK) on a read logical 
block, write logical block, read virtual block, write virtual block, read physical block, or write physical 
block I/O function. 


e Per volume—You can specify the characteristics “data check all reads” and “data check all writes” when 
the volume is mounted. The HP OpenVMS DCL Dictionary describes volume mounting and dismounting. 
The HP OpenVMS System Services Reference Manual describes the Mount Volume ($MOUNT) and 
Dismount Volume ($DISMOU) system services. 


e Per file—You can specify the file attributes “data check on read” or “data check on write.” File access 
attributes are specified when the file is accessed. Chapter 1 of this manual and the OpenVMS Record 
Management Services Reference Manual both describe file access. 


Data check is distinguished from a BACKUP/VERIFY operation, which writes an entire save set, rewinds, 
and then compares the tape to the original tape. 


See Section 3.1.10 for information on TK50 data check. 


NOTE Read and write operations with data check can result in very slow performance on streaming 
tape drives. 


3.2.6 Error Recovery 


Error recovery is aimed at performing all possible operations that enable an I/O operation to complete 
successfully. Magnetic tape error recovery operations fall into the following two categories: 


e Handling special conditions, such as power failure and interrupt timeout 
e Retrying nonfatal controller or drive errors 


The error recovery algorithm uses a combination of these types of error recovery operations to complete an I/O 
operation. 


Power failure recovery consists of repositioning the reel to the position held at the start of the I/O operation in 
progress at the time of the power failure, and then reexecuting this operation. This repositioning might or 
might not require operator intervention to reload the drives. When such operator intervention is required, 
“device not ready” messages are sent to the operator console to solicit reloading of mounted drives. Power 
failure recovery is not supported on VAXstation 2000 and MicroVAX 2000 systems. 


Device timeout is treated as a fatal error, with a loss of tape position. A tape on which a timeout has occurred 
must be dismounted and rewound before the drive position can be established. 


If a nonfatal controller/drive error occurs, the driver (or the controller, depending on the type of drive) 
attempts to reexecute the I/O operation up to 16 times before returning a fatal error. The driver repositions 
the tape before each retry. 
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The inhibit retry function modifier (IO$M_INHRETRY) inhibits all normal (nonspecial conditions) error 
recovery. If an error occurs, and the request includes that modifier, the operation is terminated immediately 
and the driver returns a failure status. IO$M_INHRETRY has no effect on power failure and timeout 
recovery. 


The driver can write up to 16 extended interrecord gaps during the error recovery for a write operation. For 
the TE16, TU45, and TU77 magnetic tape drives, writing these gaps can be suppressed by specifying the 
inhibit extended interrecord gap function modifier (IO$M_INHEXTGAP). This modifier is ignored for the 
other magnetic tape drives. 


3.2.7 Streaming Tape Systems 


Streaming tape systems, such as the TK50, TK70, TU80, TU81, TU81-Plus, TA81, and TZ30, use the supply 
and takeup reel mechanisms to control tape speed and tension directly, which eliminates the need for more 
complex and costly tension and drive components. Streaming tapes have a very simple tape path, much like 
an audio reel-to-reel recorder. 


NOTE Read and write operations with data check can result in very slow performance on streaming 
tape drives. 


Because the motors driving the reels are low-powered and because there is no tape buffering, streaming tape 
drives are not capable of starting and stopping in the interrecord gaps like conventional tape drives. When a 
streaming tape does have to stop, the following events occur: 


1. The tape slowly coasts forward to a stop. 

2. It backs up over a section previously processed. 

3. It halts to await the next command. 

4. It accelerates so that, when the original interrecord gap is encountered, the tape is moving at full speed. 


These steps, allowing the tape to reposition, require approximately one-half second to complete on TU8x tapes 
and about 3 seconds on TK50 tapes. If the operating system is not capable of writing to, or reading from, a 
streaming tape drive at a rate that will keep the drive in constant motion (streaming) the drive repositions 
itself when it runs out of commands to execute. That produces a situation known as thrashing, in which the 
relatively long reposition times exceed the time spent processing data and the result is lower-than-expected 
data throughput. 


Thrashing is entirely dependent on how fast the system can process data relative to the tape drive speed 
while streaming. Consequently, the greatest efficiency is obtained when you provide sufficient buffering to 
ensure continuous tape motion. Some streaming tape drives such as the TU80, TU81, TU81-Plus, and TA81 
are dual-speed devices that automatically adjust the tape speed to maximize data throughput and minimize 
thrashing. 


The TK50 writes up to seven filler records to keep the tape in motion. These records are ignored when the 
data is read. 


3.3. Magnetic Tape Driver Device Information 


You can obtain information on all magnetic tape device characteristics by using the Get Device/Volume 
Information ($GETDVI system service. (Refer to the HP OpenVMS System Services Reference Manual.) 
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$GETDVI returns magnetic tape characteristics when you specify the item codes DVI$_DEVCHAR, 
DVI$_DEVCHAR2, DVI$_DEVDEPEND, and DVI$_DEVDEPEND2. Tables Table 3-1, Table 3-2, and 

Table 3-4 list these characteristics. The $DEVDEF macro defines the device-independent characteristics, the 
$MTDEF macro defines the device-dependent characteristics, and the $MT2DEF macro defines the extended 
device characteristics. The extended device characteristics apply only to the TU81-Plus tape drive. 


Table 3-1 Magnetic Tape Device-Independent Characteristics 


Characteristic! Meaning 


Dynamic Bits (Conditionally Set) 


DEV$M_AVL Device is on line and available. 
DEV$M_FOR Volume is foreign. 

DEV$M_MNT Volume is mounted. 

DEV$M_RCK Perform data check on all read operations. 
DEV$M_WCK Perform data check on all write operations. 


Static Bits (Always Set) 


DEV$M_FOD Device is file-oriented. 

DEV$M_IDV Device is capable of input. 
DEV$M_ODV Device is capable of output. 
DEV$M_SQD Device is capable of sequential access. 
DEV$M_WBC2 Device is capable of write-back caching. 


1. Defined by the $DEVDEF macro. 
2. This bit is located in DVI$._ DEVCHAR2. 


Table 3-2 Device-Dependent Information for Tape Devices 
Characteristic! Meaning 
MT$M_LOST If set, the current tape position is unknown. 
MT$M_HWL If set, the selected drive is hardware write-locked. 
MT$M_EOT If set, an end-of-tape (EOT) condition was encountered by the last 
operation to move the tape in the forward direction. 
MT$M_EOF If set, a tape mark was encountered by the last operation to move the tape. 
MT$M_BOT If set, a beginning-of-tape (BOT) marker was encountered by the last 


operation to move the tape in the reverse direction. 


MT$M_PARITY If set, all data transfers are performed with even parity. If clear (normal 
case), all data transfers are performed with odd parity. Only 
nonreturn-to-zero-inverted recording at 800 bits/inch can have even parity. 


MT$V_DENSITY Specifies the density at which all data transfer operations are performed. 
MT$S_DENSITY Possible density values are as follows: 
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Table 3-2 Device-Dependent Information for Tape Devices (Continued) 
Characteristic! Meaning 
MT$K_GCR_6250 Group-coded recording, 6250 bits/inch 
MT$K_PE_1600 Phase-encoded recording, 1600 bits/inch 
MT$K_NRZI_800 Nonreturn-to-zero-inverted recording, 800 
bits/inch 
MT$K_BLK_833 Cartridge block mode recording” 
MT$V_FORMAT Specifies the format in which all data transfers are performed. A possible 
MT$S_FORMAT format value is as follows: 


MT$K_NORMAL11 Normal PDP-11 format. Data bytes are recorded 
sequentially on tape with each byte occupying 
exactly one frame. 


MT$_FASTSKIP_USED If set, the most recent IO$_SKIPFILE function was performed using the 
optimized SCSI space-by-file-marks algorithm. (See Section 3.4.4 for more 
information about the IO$M ALLOWFAST modifier to the IO$_ SKIPFILE 
function.) 


1. Defined by the $MTDEF macro. 
2. Only for the TK50 and TZ30 tape drives. 


Table 3-3 Device-Dependent Information for Tape Devices 


Characteristic! Meaning 


MT2$V_WBC_ENABLE If set, write-back caching is enabled for this unit. 
MT2$V_RDC_DISABLE If set, read caching is disabled for this unit. 


1. Defined by the $MT2DEF macro. Only for the TU81-Plus. Initial device status will show both of 
these bits cleared; write-back caching will be disabled, read caching will be enabled. 


DVI$_DEVTYPE and DVI$_DEVCLASS return the device type and class names, which are defined by the 
$DCDEF macro. DVI$_DEVBUFSIZ returns the buffer size. The buffer size is the default to be used for tape 
transfers (normally 2048 bytes). The device class for magnetic tapes is $DCTAPE, and the device type is 
determined by the magnetic tape model. For example, the device type for the TA78 is DT$_TA78; for the TA81 
it is DT$_TA81. 


This function code takes no function-dependent arguments. 


3.4 Magnetic Tape Function Codes 


The magnetic tape driver can perform logical, virtual, and physical I/O functions. Foreign-mounted devices 
do not require privileges to perform logical and virtual I/O requests. 


117 


Magnetic Tape Drivers 
Magnetic Tape Function Codes 


Logical and physical I/O functions to magnetic tape devices allow sequential access to volume storage and 
require only that the requesting process have direct access to the device. The results of logical and physical 
I/O operations are unpredictable if an ACP is present. 


Virtual I/O functions require intervention by an ACP and must be executed in a prescribed order. The normal 
order is to create and access a file, write information to that file, and deaccess the file. Subsequently, when 
you access the file, you read the information and then deaccess the file. You can write over the file when the 
information it contains is no longer useful and the file has expired. 


Any number of bytes (from a minimum of 14 to a maximum of 65,535) can be read from or written into a 
single block by a single request. The number of bytes itself has no effect on the applicable quotas (direct I/O, 
buffered I/O, and AST). Reading or writing any number of bytes subtracts the same amount from a quota. 


The volume to which a logical or virtual function is directed must be mounted for the function actually to be 
executed. If it is not, either a “device not mounted” or “invalid volume” status is returned in the I/O status 
block. 


Table 3-4 lists the logical, virtual, and physical magnetic tape I/O functions and their function codes. These 
functions are described in more detail in the following paragraphs. Chapter 1 describes the QIO level 
interface to the magnetic tape device ACP. Chapter 10 describes features to improve performance for larger 
file transfers. 


Table 3-4 Magnetic Tape I/O Functions 
Function Code Arguments Type! Function Modifiers Function 
10$_ACCESS P1,[P2],[P3], V IO$M_CREATE Search a tape for a 
[P4],[P5] I0$M_ACCESS specified file and access 
the file if found and 
IO$M_ACCESS is set. If 
the file is not found and 
IO$M_CREATE is set, 
create a file at end-of-tape 
(EOT) marker. 
I0$_ACPCONTROL  P1,[P2],[P3], V IO$M_DMOUNT Perform miscellaneous 
[P4], [P5] control functions. ” 
IO$_ AVAILABLE Pp Clear volume valid bit. 
10$_CREATE P1,[P2][,[P3], Vv IO0$M_CREATE Create a file. 
[P4],[P5] IO$M_ACCESS 
10$_DEACCESS P1,[P2],[P3], V Deaccess a file and, if the 
[P4],[P5] file has been written, write 
out trailer records. 
10$_DSE® P IO$M_NOWAIT Erase a prescribed section 
of the tape. 
10$_FLUSH L Flush the controller cache 
to tape. 
10$_MODIFY P1,[P2],[P3], V Write user labels. 
[P4],[P5] 
10$_PACKACK P Initialize volume valid bit. 
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Table 3-4 Magnetic Tape I/O Functions (Continued) 
Function Code Arguments Type! Function Modifiers Function 
10$_READLBLK* _ P1,P2 L IO$M_DATACHECK® _ Read logical block. 
IO$M_INHRETRY 
IO$M_REVERSE® 
IO$_READPBLK P1,P2 P 10$M_DATACHECK® Read physical block. 
IO$M_INHRETRY 
IO$M_REVERSE® 
I0$_READVBLK P1,P2 V 10$M_DATACHECK® Read virtual block. 
IO$M_INHRETRY 
IO$M_REVERSE® 
I0$_REWIND L IO0$M_INHRETRY Reposition tape to the 
IO$M_NOWAIT beginning-of-tape (BOT) 
IO0$M_RETENSION marker. 
I0$_REWINDOFF L IO$M_INHRETRY Rewind and unload the 
IO$M_NOWAIT tape on the selected drive. 
IO$M_RETENSION 

10$_SENSECHAR [P1],[P2]7 P I0$M_INHRETRY Sense the tape 
characteristics and return 
them in the I/O status 
block. 

IO$_SENSEMODE _ [pqj,[P2]7 L 10$M_INHRETRY Sense the tape 
characteristics and return 
them in the I/O status 
block. 

I0$_SETCHAR P1,[P2]7 P Set tape characteristics for 
subsequent operations. 

10$_SETMODE P1,[P2]” L Set tape characteristics for 
subsequent operations. 

10$_SKIPFILE Pl L IO0$M_INHRETRY Skip past a specified 
10$M_NOWAIT® number of tape marks in 
10$M_ALLOWFAST either a forward or reverse 
direction. 
IO$_SKIPRECORD P11 L IO$M_INHRETRY Skip past a specified 
10$M_NOWAIT® number of blocks in either 
a forward or reverse 
direction. 

10$_ UNLOAD L IO$M_INHRETRY Rewind and unload the 


IO0$M_NOWAIT 


tape on the selected drive. 
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Table 3-4 


Magnetic Tape I/O Functions (Continued) 


Function Code 


Arguments 


Type 


1 


Function Modifiers 


Function 


10$_WRITELBLK 


10$_WRITEOF 


10$_WRITEPBLK 


P1,P2 


P1,P2 


L 


I0$M_ERASE? 


10$M_DATACHECK® 
10$M_INHRETRY 


I0$M_INHEXTGAP!° 
IO$M_NOWAIT® 


IO$M_INHRETRY 


I0$M_INHEXTGAP!° 
10$M_NOWAIT 


IO$M_ERASE? 


Write logical block. 


Write an extended 
interrecord gap followed 
by a tape mark. 


Write physical block. 


IO$M_DATACHECK® 
10$M_INHRETRY 


I0$M_INHEXTGAP!° 
10$M_NOWAIT® 


10$_WRITEVBLK P1,P2 Vv Write virtual block. 


I10$M_DATACHECK® 
10$M_INHRETRY 
I0$M_INHEXTGAP!° 


IO$M_NOWAIT® 


. V= virtual; L = logical; P = physical. 

. See Section 1.6.8. 

. Only for TMSCP drives, and TZK50, and TZ30 tape devices. 

. On OpenVMS Alpha, P1 supports a 64-bit address. 

. Not for TS04 and TU80 tape devices. 

. Not for TUK50 and TQK50 tape devices. 

. The P1 and P2 arguments for IO$_SENSEMODE and IO$_SENSECHAR and the P2 argument for 
10$_SETMODE and I0$_SETCHAR are for TMSCP drives only. 

8. Only for RV20, TA90, and TU81-Plus drives. 

9. Takes no arguments; valid only for TMSCP drives, and TZK50 and TZ30 tape devices. 

10.Only for TE16, TU45, and TU77 tape devices. 


NOok WN FH 


The function-dependent arguments for IO$_CREATE, IO$_ACCESS, IO$_DEACCESS, IO$_MODIFY, 
IO$_ ACPCONTROL are as follows: 


e P1—The address of the file information block (FIB) descriptor. 


e P2—Optional. The address of the file name string descriptor. If specified with IO$_ACCESS, the name 
identifies the file being sought. If specified with IO$_CREATE, the name is the name of the created file. 


e P3—Optional. The address of the word that is to receive the length of the resultant file name string. 
e P4—Optional. The address of a descriptor for a buffer that is to receive the resultant file name string. 


e P5—Optional. The address of a list of attribute descriptors. If specified with IO$_ACCESS, the attributes 
of the file are returned to the user. If specified with IO$_CREATE, P5 is the address of the attribute 
descriptor list for the new file. All file attributes for IO$_MODIFY are ignored. 


See Chapter 1 for more information on these functions. 
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The function-dependent arguments for IO$_READVBLK, IO$_READLBLK, IO$_READPBLK, 
I0$_WRITEVBLK, I10$_WRITELBLK, and IO$_WRITEPBLK are as follows: 


e P1—tThe starting virtual address of the buffer that is to receive the data in the case of a read operation; 
or, in the case of a write operation, the virtual address of the buffer that is to be written on the tape. On 
OpenVMS Alpha, P1 can be a 64-bit address. 


e P2—The length of the buffer specified by P1. 
The function-dependent argument for IO$_SKIPFILE and I0$_SKIPRECORD is: 


P1—tThe number of tape marks to skip over in the case of a skip file operation; or, in the case of a skip 
record operation, the number of blocks to skip over. If a positive number is specified, the tape moves 
forward; if a negative number is specified, the tape moves in reverse. (The maximum number of tape 
marks or records that P1 can specify is 32,767.) 


Example 3-1 shows the correct method of defining the P1 parameter in an IO$_SKIPRECORD QIO. 


Example 3-1 Defining the P1 Parameter in a IO$_SKIPRECORD QIO 
TAPE_CHAN: 
.» WORD 0 
IOSB: .» WORD 0 
.» WORD 0) 
. LONG 0 
DEVICE: .ASCID /$127$MUA0:/ 
RECORD: .LONG 2000 


» PSECT CODE, EXE, NOWRT 


- ENTRY MT_IO, “M 


SASSIGN_S CHAN=TAPE_CHAN, — 
DEVNAM=DEVICE 
BLBC RO, EXIT_ERROR 


SQIOW_S CHAN=TAPE_CHAN, — 
FUNC=#I0$_SKIPRECORD, - 
IOSB=IOSB, — 

P1=RECORD 

BLBC RO, EXIT_ERROR 

SEXIT_S RO 


EXIT_ERROR: 
SEXIT_S RO 
- END MT_IO 
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3.4.1 Read 


The read function reads data into a specified buffer in the forward or reverse direction starting at the next 
block position. 


The operating system provides the following read function codes: 
e 1O0$ READVBLK—Read virtual block 

e 10$_READLBLK—Read logical block 

e J0$_READPBLK—Read physical block 


If a read virtual block function is directed to a volume that is mounted foreign, it is converted to a read logical 
block function. If a read virtual block function is directed to a volume that is mounted structured, the volume 
is handled the same way as a file-structured device. 


Two function-dependent arguments are used with these codes: P1 and P2. These arguments are described in 
Section 3.4. 


If the read function code includes the reverse function modifier IO$M_REVERSE), the drive reads the tape 
in the reverse direction instead of the forward direction. IO$M_REVERSE cannot be specified for the TUK50 
and TQK50 devices. 


The data check function modifier (IO$M DATACHECK) can be used with all read functions. If this modifier 
is specified, a data check operation is performed after the read operation completes. (The drive performs a 
space reverse or space forward between the read and data check operations.) A data check operation is also 
performed if the volume that was read, or the volume on which the file resides (virtual read), has the 
characteristic “data check all reads.” Furthermore, a data check is performed after a virtual read if the file 
has the attribute “data check on read.” The TS04 and TU80 tape drives do not support the data check 
function. 


For read physical block and read logical block functions, the drive returns the status SS$_NORMAL (not 

end-of-tape status) if either of the following conditions occurs and no other error condition exists: 

e The tape is positioned past the end-of-tape (EOT) position at the start of the read (forward or reverse) 
operation. 

e The tape enters the EOT region as a result of the read (forward) operation. 

The transferred byte count reflects the actual number of bytes read. 

If the drive reads a tape mark during a logical or physical read operation in either the forward or reverse 

direction, any of the following conditions can return an end-of-file (EOF) status: 

e The tape is positioned past the EOT position at the start of the read operation. 

e The tape enters the EOT region as a result of the read operation. 

e The drive reads a tape mark as a result of a read operation but the tape does not enter the EOT region. 


An EOF status is also returned if the drive attempts a read operation in the reverse direction when the tape 
is positioned at the beginning-of-tape (BOT) marker. All conditions that cause an EOF status result in a 
transferred byte count of zero. 


If the drive attempts to read a block that is larger than the specified memory buffer during a logical or 
physical read operation, a data overrun status is returned. The buffer receives only the first part of the block. 
On a read in the reverse direction (on drives other than the TK50 and TZ30) the buffer receives only the latter 
part of the block. The transferred byte count is equal to the actual size of the block. Read reverse starts at the 
top of the buffer. Therefore, the start of the block is at P1 plus P2 minus the length read. The TUK50 and 
TZ30 cannot actually perform read reverse operations; they must be simulated by the driver. Therefore, the 
data returned are those that would have been returned had the block been read in the forward direction. 
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It is not possible to read a block that is less than 14 bytes in length. Records that contain less than 14 bytes 
are termed “noise blocks” and are completely ignored by the driver. 


3.4.2 Write 


The write function writes data from a specified buffer to tape in the forward direction starting at the next 
block position. 


The operating system provides the following write function codes: 


¢ 10$_WRITEVBLK—Write virtual block 
¢ 10$_WRITELBLK—Write logical block 
¢ I0$_WRITEPBLK—Write physical block 


If a write virtual block function is directed to a volume that is mounted foreign, the function is converted to a 
write logical block. If a write virtual block function is directed to a volume that is mounted structured, the 
volume is handled the same way as a file-structured device. 


Two function-dependent arguments are used with these codes: P1 and P2. These arguments are described in 
Section 3.4. 


The IO$M_ERASE function modifier can be used with the IO$_ WRITELBLK and IO$_WRITEPBLK function 
codes to erase a user-selected part of a tape. This modifier propagates an erase pattern of all zeros from the 
current tape position to 10 feet past the EOT position and then rewinds to the BOT marker. 


The data check function modifier (IO$M DATACHECK) can be used with all write functions. If this modifier 
is specified, a data check operation is performed after the write operation completes. (The drive performs a 
space reverse between the write and the data check operations.) The driver forces a data check operation 
when an error occurs during a write operation. This ensures that the data can be reread. A data check 
operation is also performed if the volume written, or the volume on which the file resides (virtual write), has 
the characteristic “data check all writes.” Furthermore, a data check is performed after a virtual write if the 
file has the attribute “data check on write.” The TS04 and TU80 tape drives do not support the data check 
function. 


If the IO$M_NOWAIT function modifier is specified, write-back caching is enabled on a per-command basis. 
IO0$M_NOWAIT is applicable only to TU81-Plus drives. 


If the drive performs a write physical block or a write logical block operation, an EOT status is returned if 
either of the following conditions occurs and no other error condition exists: 


e The tape is positioned past the EOT position at the start of the write operation. 
e The tape enters the EOT region as a result of the write operation. 


The transferred byte count reflects the size of the block written. It is not possible to write a block less than 14 
bytes in length. An attempt to do so results in the return of a bad parameter status for the QIO request. 


3.4.3 Rewind 


The rewind function repositions the tape to the beginning-of-tape (BOT) marker. 


If the IO$M_NOWAIT function modifier is specified, the I/O operation is completed when the rewind is 
initiated. Otherwise, I/O completion does not occur until the tape is positioned at the BOT marker. 


If the IO$M_RETENSION function modifier is specified and the device supports the retension operation, the 
rewind function positions the tape to the physical-end-of-tape (EOT) marker and rewinds the tape to the BOT 
marker. If the tape does not support the IO$M_RETENSION modifer, a SS$_ILLIOFUNC error is returned. 
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IO0$_REWIND has no function-dependent arguments. 


3.4.4 Skip File 


The skip file function (IO$_SKIPFILE) skips past a specified number of tape marks in either a forward or 
reverse direction. A function-dependent argument (P1) is provided to specify the number of tape marks to be 
skipped, as shown in Figure 3-1. If a positive file count is specified, the tape moves forward; if a negative file 
count is specified, the tape moves in reverse. (The actual number of files skipped is returned as an unsigned 
number in the I/O status block.) 


Figure 3-1 10$_SKIPFILE Argument 
31 16 15 0 


ZK0671GE 


Only tape marks (when the tape moves in either direction) and the BOT marker (when the tape moves in 
reverse) are counted during a skip file operation. The BOT marker terminates a skip file function in the 
reverse direction. The end-of-tape (EOT) marker does not terminate a skip file function in either the forward 
or reverse direction. A negative skip file function leaves the tape positioned just before a tape mark (at the 
end of a file) unless the BOT marker is encountered, whereas a positive skip file function leaves the tape 
positioned just past the tape mark. 


A skip file function in the forward direction can also be terminated if two consecutive tape marks are 
encountered. Section 3.4.5.1 describes this feature. 


The IO$M_ALLOWFAST modifier can be used with the IO$_SKIPFILE function to provide better 
performance on SCSI tape drives that support the SCSI space-by-file-marks command and the SCSI read 
position command. 


When the IO$¢M_ALLOWFAST modifier is specified, a tape operation skips over consecutive tape marks that 
are not immediately before the end-of-data position on the medium. However, if two consecutive tape marks 
are detected immediately before the end-of-data position on the tape, the tape is positioned between these two 
tape marks and the SS$_ENDOFVOLUME status is returned. 


The IO$M_ALLOWFAST modifier allows a SCSI tape subsystem to use the optimized IO$_SKIPFILE if it is 
capabable. If a specific tape device does not adequately support the optimized IO$_SKIPFILE that uses the 
SCSI space-by-file-marks command, the tape subsystem will use the standard space-by-records algorithm. 


3.4.5 Skip Record 


The skip record function skips past a specified number of physical tape blocks in either a forward or reverse 
direction. A device- or function-dependent argument (P1) specifies the number of blocks to skip, as shown in 
Figure 3-2. If a positive block count is specified, the tape moves forward; if a negative block count is specified, 
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the tape moves in reverse. The actual number of blocks skipped is returned as an unsigned number in the I/O 
status block. If a tape mark is detected, the count is the number of blocks skipped, plus 1 (forward tape 
motion) or minus 1 (reverse tape motion). 


Figure 3-2 10$_SKIPRECORD Argument 
31 16 15 0 


ZK0672GE 


A skip record operation is terminated by the end-of-file (HOF) marker when the tape moves in either 
direction, by the BOT marker when the tape moves in reverse, and by the EOT marker when the tape moves 
forward. 


A skip record function in the forward direction can also be terminated if the tape was originally positioned 
between two tape marks. Section 3.4.5.1 describes this feature. 


3.4.5.1 Logical End-of-Volume (EOV) Detection 


A skip file or skip record operation that uses the standard space-by-records algorithm is terminated when two 
consecutive tape marks are encountered when the tape moves in the forward direction. After the operation 
terminates, the tape remains positioned between the two tape marks that were detected. The I/O status block 
(IOSB) returns the status SS$_ ENDOFVOLUME and the actual number of files (or records) skipped during 
the operation prior to the detection of the second tape mark. The skip count is returned in the high-order 
word of the first longword of the IOSB. 


An optimized skip file that uses the IO$M_ALLOWFAST modifier is terminated when the end-of-data 
position is encountered. If two consecutive tape marks immediately precede the end-of-data position on the 
tape, the tape is positioned between these two tape marks. The SS$_ENDOFVOLUME status and the skip 
count are returned in the IOSB. 


Subsequent skip record (or skip file) requests terminate immediately when the tape is positioned between the 
two tape marks, producing no net tape movement and returning the SS$_ENDOFVOLUME status with a 
skip count of zero. 


To move the tape beyond the second tape mark, you must employ another I/O function. For example, the 
IO0$_READLBLK function, if issued after receipt of the SS$_ENDOFVOLUME status return, terminates with 
an SS$_ENDOFFILE status and with the tape positioned just past the second tape mark. From this new 
position, other skip functions could be issued to produce forward tape motion (assuming there is additional 
data on the tape). 


If three consecutive tape marks are encountered during a skip file function, you must issue two 
I0$_READLBLK functions, the first to get the SS$_ENDOFFILE return and the second to position the tape 
past the third tape mark. 


3.4.6 Write End-of-File 


The write end-of-file (EOF) function writes an extended interrecord gap (of approximately 3 inches for 
nonreturn-to-zero-inverted (NRZI) recording and 1.5 inches for phase-encoded (PE) recording) followed by a 
tape mark. No device- or function-dependent arguments are used with IO$_WRITEOF. 


An end-of-tape (EOT) status is returned in the I/O status block if either of the following conditions is present 
and no other error conditions occur: 
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e Awrite EOF function is executed while the tape is positioned past the EOT marker. 


e Awrite EOF function causes the tape position to enter the EOT region. 


3.4.7 Rewind Offline 


The rewind offline function rewinds and unloads the tape on the selected drive. 


The I/O operation is completed as soon as the tape movement is initiated. The actual finish of the mechanical 
rewind or unload operation may occur long after the I/O operation completes. 


If the IO$M_RETENSION function modifier is specified and the device supports the retension operation, the 
rewind offline function positions the tape to the physical end-of-tape (KOT) marker and rewinds the tape to 
the beginning-of-tape (BOT) marker. If the tape does not support the IO$M_RETENSION modifer, a 
SS$_ILLIOFUNC error is returned. 


No device- or function-dependent arguments are used with IO$_REWINDOFF. 


3.4.8 Unload 


The unload function rewinds and unloads the tape on the selected drive. The unload function is functionally 
the same as the rewind offline function. If the IO$M_NOWAIT function modifier is specified, the I/O 
operation is completed as soon as the rewind operation is initiated. No device- or function-dependent 
arguments are used with IO$_UNLOAD. 


3.4.9 Sense Tape Mode 


The sense tape mode function senses the current device-dependent and extended device characteristics (see 
Tables Table 3-2 and Table 3-4). 


The operating system provides the following function codes: 
e I0$ SENSEMODE—Sense mode 
e I0$ _SENSECHAR—Sense characteristics 


Sense mode requires logical I/O privilege. Sense characteristics requires physical I/O privilege. For TMSCP 
drives, the sense mode function returns magnetic tape information in a user-supplied buffer, which is 
specified by the following function-dependent arguments: 


e P1—Optional. Address of a user-supplied buffer. 
e P2—Optional. Length of a user-supplied buffer. 
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If P1 is not zero, the sense mode buffer returns the tape characteristics. (If P2=8, the second longword of the 
buffer contains the device-dependent characteristics. If P2=12, the second longword contains the 
device-dependent characteristics and the third longword contains the tape densities that the drive supports 
and the extended tape characteristics.) The extended characteristics are identical to the information returned 
by DVI$_DEVDEPEND2 (see Table 3-4). Figure 3-3 shows the contents of the P1 buffer. 


Figure 3-3 Sense Mode P1 Buffer 


P2=8: 
3 16 15 8 7 0 


1 
Tape Characteristics * 


* From UCB$L_DEVDEPEND 


P2=12: 
3 16 15 8 7 0 


{ 
Tape Characteristics * 


Extended Tape Characteristics * * Supported Densities * * 


“From UCB$L_DEVDEPEND 
“ From UCB$L_DEVDEPND2 


ZK4854GE 


3.4.10 Set Mode 


Set mode operations affect the operation and characteristics of the associated magnetic tape device. The 
operating system defines two types of set mode functions: set mode and set characteristics. 


Set mode requires logical I/O privilege. Set characteristics requires physical I/O privilege. The following 
function codes are provided: 


e I0$ SETMODE—Set mode 

e I0O$ SETCHAR—Set characteristics 

These functions take the following device- or function-dependent arguments (other arguments are ignored): 
e P1i—The address of a characteristics buffer. 


e P2—Optional. The length of the characteristics buffer. The default is 8 bytes. If a length of 12 bytes is 
specified, the third longword (which is for TMSCP drives only) specifies the extended tape characteristics. 
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Figure 3-4 shows the P1 characteristics buffer for IO$_SETMODE. Figure 3-5 shows the same buffer for 
IO$_SETCHAR. 


Figure 3-4 Set Mode Characteristics Buffer for I0O$_SETMODE 
P2=8: 
3 16 15 0 


1 
Buffer Size Not Used 
Tape Characteristics 


P2=12: 
31 16 15 0 


Buffer Size Not Used 
Tape Characteristics 


Extended Tape Characteristics 


ZK4856GE 
Figure 3-5 Set Mode Characteristics Buffer for IO$_SETCHAR 
P2=8: 
31 16 15 8 7 0 


Tape Characteristics 


P2=12: 
3 16 15 87 0 


{ 
Tape Characteristics 


Extended Tape Characteristics 


ZK4855GE 


The first longword of the P1 buffer for the set characteristics function contains information on device class 
and type, and the buffer size. The device class for tapes is DC$_TAPE. 
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The $DCDEF macro defines the device type and class names. The buffer size is the default to be used for tape 
transfers (this default is normally 2048 bytes). 


The second longword of the P1 buffer for both the set mode and set characteristics functions contains the tape 
characteristics. Table 3-5 lists the tape characteristics and their meanings. The $MTDEF macro defines the 
symbols listed. If P2=12, the third longword contains the extended tape characteristics for TMSCP drives, 
which are listed in Table 3-6. The extended tape characteristics are defined by the $MT2DEF macro and are 
identical to the information returned by DVI$_DEVDEPEND2. 


Table 3-5 Set Mode and Set Characteristics Magnetic Tape Characteristics 
Characteristic! Meaning 
MT$M_PARITY If set, all data transfers are performed with even parity. If clear (normal 


case), all data transfers are performed with odd parity. Even parity can 
be selected only for nonreturn-to-zero-inverted recording at 800 
bits/inch. Even parity cannot be selected for phase-encoded recording 
(tape density is MT$K_PE_1600) or group-coded recording (tape 
density is MT$K_GCR_6250) and is ignored. 


MT$V_DENSITY Specifies the density at which all data transfers are performed. Tape 
MT$S_DENSITY density can be set only when the selected drive's tape position is at the 
BOT marker. Possible density values are as follows: 
MT$K_DEFAULT Default system density. 
MT$K_GCR_6250 Group-coded recording, 6250 bits/inch. 
MT$K_PE_1600 Phase-encoded recording, 1600 bits/inch. 
MT$K_NRZI_800 Nonreturn-to-zero-inverted recording, 800 
bits/inch. 
MT$K_BLK_833 Cartridge block mode recording.” 
MT$V_FORMAT Specifies the format in which all data transfers are performed. Possible 
MT$S_FORMAT format values are as follows: 
MT$K_DEFAULT Default system format. 
MT$K_NORMAL11 Normal PDP-11 format. Data bytes are 


recorded sequentially on tape with each 
byte occupying exactly one frame. 


1. Defined by the $MTDEF macro. 
2. Only for the TK50 and TZ30. 


Table 3-6 Extended Device Characteristics for Tape Devices 
Characteristic! Meaning 
MT2$V_WBC_ENABLE Enable write-back caching on a per-unit basis. 
MT2$V_RDC_DISABLE Disable read caching on a per-unit basis. 


1. Defined by the $MT2DEF macro. Only for TU81-Plus drives. 
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Application programs that change specific magnetic tape characteristics should perform the following steps, 
as shown in Example 3-2 in Section 3.6: 


1. Use the IO$- SENSEMODE function to read the current characteristics. 
2. Modify the characteristics. 
3. Use the set mode function to write back the results. 


Failure to follow this sequence will result in clearing any previously set characteristic. 


3.4.11 Multiple Tape Density Support 


As of Version 7.2, OpenVMS Alpha permits the selection of any density and any compression supported by a 
tape drive. You can write to tapes using any density and any compression algorithm supported by the tape 
drive. Exchanging tapes among tape drives with different default settings for density or compression is much 
easier with this enhancement. 


Mutiple tape density support is provided by changes in the QIO interface. These changes are guided by 
device/density tables in system libraries and the corresponding class drivers. This enhancement functions 
with tape drives that support multiple tape density switching via the standard MODE_SENSE and 
MODE_SELECT mechanisms. All density and compression options available for a given drive will be 
accessible by the system. The QIO interface uses MT3DEF to identify the drives, and to match them with 
their density and compression code options. Some newer drives may not be included in the module. 


NOTE After the media has been initialized to a specific density, it will remain that density until the 
media is initialized to a different density. For example, if an HP media has been initialized with 
TK86 density, the DCL command MOUNT/DENSITY=TK85 will have no effect because the 
media is initialized at TK86 density. Likewise, BACKUP/DENSITY=TK85 will have no effect if 
the media is initialized at TK86 density. However, BACKUP/DENS=TK85/INITIALIZE will 
initialize the media to TK85 density. 


These enhancements allow IO$_SETMODE and IO$_SENSEMODE to function with most density values and 
a wider variety of drives. The system management utilities BACKUP and MOUNT take advantage of this 
added functionality. For more information about multiple tape density support with these utilities, refer to 
the HP OpenVMS System Management Utilities Reference Manual. For more information about 
enchancements in INITIALIZE, refer to the HP OpenVMS DCL Dictionary. 


3.4.12 Data Security Erase 


The data security erase function erases all data from the current position of the volume to 10 feet beyond the 
EOT reflective strip, and then rewinds the tape to the BOT marker. It is a physical I/O function and requires 
the access privilege necessary to perform physical I/O functions. The following function code is provided: 


10$_DSE 
If the function is issued when a tape is positioned at the BOT marker, all data on the tape will be erased. 


10$_DSE takes no device- or function-dependent arguments. 


3.4.13 Modify 


Specifying the ATR$C_USERLABEL or ATR$C_ENDLBLAST attributes with IO$_MODIFY results in a bad 
attribute error. If any other attributes are specified, the IO$_MODIFY function is treated as a no-operation; 
that is, the function returns success, but no action is performed. 
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3.4.14 Pack Acknowledge 


The pack acknowledge function sets the volume valid bit for all magnetic tape devices. It is a physical I/O 
function and requires the access privilege to perform physical I/O. The following function code is provided: 


10$_PACKACK 


IO0$_PACKACK must be the first function issued when a volume is placed in a magnetic tape drive. 
I0$_PACKACK is issued automatically when the DCL commands INITIALIZE or MOUNT are issued. 


3.4.15 Available 


The available function clears the volume valid bit for all magnetic tape drives, that is, it reverses the function 
performed by the pack acknowledge function (see the Section 3.4.14). A rewind of the tape is performed 
(applicable to all tape drives). No unload function is issued to the drive. The following function code is 
provided: 


10$_AVAILABLE 


This function takes no function-dependent arguments. 


3.4.16 Flush 


The flush function is used to ensure that all previously issued cached commands have fully completed. 
Normally, hosts use this function to establish or maintain synchronization with write-back cached commands 
issued to the specified tape unit. The I/O request does not complete until all cached data is written 
successfully to the media in the exact order that the user specified. 


10$_FLUSH 


This function code takes no function-dependent arguments. 


3.5 V/O Status Block 


The I/O status block (IOSB) for QIO functions on magnetic tape devices is shown in Figure 3-6. Appendix A 
lists the status returns for these functions. (The OpenVMS system messages documentation provides 
explanations and suggested user actions for these returns.) Table 3-2 (in Section 3.3) lists the 
device-dependent data returned in the second longword. The IO$_SENSEMODE function can be used to 
return that data. 


Figure 3-6 IOSB Contents 


31 16 15 0 


DeviceDependent Data 


ZK0675GE 
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The byte count is the actual number of bytes transferred to or from the process buffer or the number of files or 
blocks skipped. (If an IO$_SKIPRECORD function is terminated by the detection of a tape mark, the count 
returned in the IOSB is an unsigned number reflecting the number of blocks skipped, plus 1. 


3.6 Magnetic Tape Drive Programming Examples 


This section presents magnetic tape driver VAX MACRO programming examples. 


Example 3-2 shows the recommended sequence for changing a device characteristic. It retrieves the current 
characteristics using an IO$_SENSEMODE request, sets the new characteristics bits, and then uses 
I0$_SETMODE to set the new characteristics. 


Example 3-3 shows ways of specifying sense mode and set mode, both with and without a user buffer 
specified, and with user buffers of different lengths. 


In addition, Example 3-4 shows how data is written to and read from magnetic tape through the magnetic 
tape ACP. 


Example 3-2 Device Characteristic Program Example 
SQIOW_S - ; Get current characteristics. 
FUNC = #I0$_SENSEMODE, - ; -— Sense mode 
CHAN = CHANNEL, - 7 — Channel 
IOSB = IO_STATUS, - ; -— IOSB 
Pl = BUFFER, — ; — User buffer supplied 
P2 = #12 ; -— Buffer length = 12 


(Check for errors) 


(Set desired characteristics bits) 


SQIOW_S - ; Set new characteristics. 
FUNC = #IO0$_SETMODE, - ; -— Set Mode 
CHAN = CHANNEL, - ; — Channel 
IOSB = IO_STATUS,- 7 = TOSB 
Pl = BUFFER, -— ; — User buffer address 
P2 = #12 ; -— Buffer length = 12 


(Check for errors) 
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-PSECT 


SIODEF 


DEVICE_NAME: 
-ASCID 
CHANNEL: 
.» WORD 
BUFFER: .BLKL 
IO_STATUS: 
- QUAD 
»-PSECT 
. ENTRY 
SASSIGN_S - 
DEVNAM 
CHAN 
BSBW ERR_CHECK2 
SQIOW_S - 
FUNC 
CHAN 
IOSB 
BSBW ERR_CHECK 
SQIOW_S - 
FUNC 
CHAN 
IOSB 
Pl 
BSBW ERR_CHECK 
SQIOW_S — 
FUNC 
CHAN 
IOSB 
P1 
P2 
BSBW ERR_CHECK 
SQIOW_S - 
FUNC 
CHAN 
IOSB 
Pl 
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Set Mode and Sense Mode Program Example 


IMPURE, 


/MUAO / 


CODE, RD, 


MAIN, *M 


= DEVICE_NAME, - 
= CHANNEL 


= #1I10$_SENSEMOD 
= CHANNEL, - 
= IO_STATUS 


#IO$_SENSEMODE 
CHANNEL, — 
IO_STATUS, — 
BUFFER 


= #IO0$_SENSEMODE 


CHANNEL, - 
IO_STATUS, - 
BUFFER, - 

= #8 


= #I0$_SENSEMODE, 


CHANNEL, — 
IO_STATUS, — 


BUFFER, — 


NOWRT, 


NOEXE, NOSHR 


; Name of device 


; Channel to device 


; Set/Sense characteristics 
; buffer 


; Final I/O status 


EXE 


; Assign a channel to device 
, 


, 
; Check for errors 


; Get current characteristics 
E,-; No user buffer supplied 
, 


, 


; Check for errors 


; Get current characteristics 
,-; User buffer supplied, length 
; Gefaulted 
, 


, 
; Check for errors 


; Get current characteristics 
,-; User buffer supplied, length 


; Check for errors 


; Get extended characteristics 
-; User buffer supplied, length 
i = 12 


133 


Magnetic Tape Drivers 
Magnetic Tape Drive Programming Examples 


P2 = #12 
BSBW ERR_CHECK 
SQIOW_S 
FUNC = #10$_SETMODE, - 
CHAN = CHANNEL, - 
IOSB = IO_STATUS, - 
P1 = BUFFER 
BSBW ERR_CHECK 
SQIOW_S - 
FUNC = #10$_SETMODE, - 
CHAN = CHANNEL, - 
IOSB = IO_STATUS, - 
Pl = BUFFER, - 
P2 = #8 
BSBW ERR_CHECK 
SQIOW_S - 
FUNC = #10$_SETMODE, - 
CHAN = CHANNEL, - 
IOSB = IO_STATUS, - 
Pl = BUFFER, - 
P2 = #12 
BSBW ERR_CHECK 
RET 
. ENABLE LSB 
ERR_CHECK: 
BLBS IO_STATUS, ERR_CHECK2 
MOVZWL IO_STATUS,-(SP) 
BRB 10$ 
ERR_CHECK2: 
BLBS RO, 20$ 
PUSHL RO 
108: CALLS #1,G*LIBSSTOP 
208: RSB 
.DISABLE LSB 
. END MAIN 
Example 3-4 


NeoNe 


. TITLE 


-IDENT /01/ 
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, 


, 


’ 
’ 
’ 
, 
’ 


’ 


’ 


MAGTAPE PROGRAMMING EXAMPLE 


Check for errors 


; Length defaulted 


Check for errors 


Set new characteristics 
; Length = 8 


’ 


Check for errors 


Set extended characteristics 
Length = 12 


Check for errors 


; Continue if good IOSB 
; Otherwise, set up for stop 


; Branch to common code 


; Continue if good status 
; Otherwise, set up for stop 
; Stop execution 


MAGNETIC_TAPE.MAR Device Characteristic Program Example 
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; Define necessary symbols. 


SFIBDEF ;Define file information block 
7symbols 
SIODEF ;Define I/O function codes 


; Allocate storage for the necessary data structures. 


; Allocate magtape device name string and descriptor. 


TAPENAME: : 
. LONG 20$-10$ ;Length of name string 
. LONG 10$ ;Address of name string 
108: -ASCII /TAPE/ ;Name string 
20S: ;Reference label 


, 
; Allocate space to store assigned channel number. 


, 


TAPECHAN: ; 

. BLKW 1 ;Tape channel number 
, 
; Allocate space for the I/O status quadword. 


, 


IOSTATUS: ; 

. BLKQ 1 7I/O status quadword 
, 
; Allocate storage for the input/output buffer. 


, 


BUFFER: r 
.REPT 256 ; Initialize buffer to 
-ASCII /A/ ;contain 'A' 
.ENDR ; 


; Now define the file information block (FIB), which the ACP uses 

; in accessing and deaccessing the file. Both the user and the ACP 
; supply the information required in the FIB to perform these 

; functions. 


FIB_DESCR: ;Start of FIB 
. LONG ENDFIB-FIB ;Length of FIB 
. LONG FIB ;Address of FIB 
FIB: . LONG FIBSM_WRITE!FIBSM_NOWRITE ;Read/write access allowed 
. WORD 0,0,0 ;File ID 
. WORD 0,0,0 ;Directory ID 
. LONG 0 ; Context 
. WORD 0 ;Name flags 
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. WORD 0 ;Extend control 
ENDFIB: ;Reference label 


; Now define the file name string and descriptor. 


NAME_DESCR: ; 


. LONG END_NAME-NAME ;File name descriptor 

. LONG NAME ;Address of name string 
NAME: -ASCII "MYDATA.DAT;1" ;File name string 
END_NAME: ;Reference label 


, 
KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KK 
, 


i Start Program 


KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK 


; The program first assigns a channel to the magnetic tape unit and 

; then performs an access function to create and access a file called 

; MYDATA.DAT. Next, the program writes 26 blocks of data (the letters 

, of the alphabet) to the tape. The first block contains all A's, the 

; next, all B's, and so forth. The program starts by writing a block of 
, 256 bytes, that is, the block of A's. Each subsequent block is reduced 
; in size by two bytes so that by the time the block of Z's is written, 

; the size is only 206 bytes. The magtape ACP does not allow the reading 
; of a file that has been written until one of three events occurs: 


; 1. The file is deaccessed. 
7 2. The file is rewound. 
; 3. The file is backspaced. 


; In this example the file is backspaced zero blocks and then read in 
; veverse (incrementing the block size every block); the data is 

; checked against the data that is supposed to be there. If no data 
7 errors are detected, the file is deaccessed and the program exits. 


.ENTRY MAGTAPE_EXAMPLE, *M, R4,R5,R6,R7, R8> 


; First, assign a channel to the tape unit. 


SASSIGN_S TAPENAME, TAPECHAN ;Assign tape unit 
CMPW #SSS_NORMAL, RO ; Success? 
BSBW ERRCHECK ;Find out 


, 
; Now create and access the file MYDATA.DAT. 


, 


SQIOW_S CHAN=TAPECHAN, — 7Channel is magtape 
FUNC=#1I0$_CREATE! IOSM_ACCESS! IOSM_CREATE, -; Function 
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- jis create 
IOSB=IOSTATUS, - j;Address of I/O status 


a ;word 
P1=FIB_DESCR, - ;FIB descriptor 
P2=#NAME_DESCR 7;Name descriptor 
CMPW SSS_NORMAL, RO ; Success? 
BSBW ERRCHECK ‘Find out 


LOOP1 consists of writing the alphabet to the tape (see previous 


; description). 
v 
MOVL #26,R5 ;Set up loop count 
MOVL #256,R3 ;Set up initial byte count 
;in R3 
LOOP1: ;Start of loop 
SQIOW_S CHAN=TAPECHAN, — 7Perform QIOW to tape channel 
FUNC=#1I0$_WRITEVBLK, — ;Function is write virtual 
= block 
P1=BUFFER, — ;Buffer address 
P2=R3 ;Byte count 
CMPW SSS_NORMAL, RO ; Success? 
BSBW ERRCHECK ;Find out 


a 
, 


, 


Now decrement the byte count in preparation for the next write 
operation and set up a loop count for updating the character 
written; LOOP2 performs the update. 


SUBL2 #2,R3 ;Decrement byte count for 
;next write 

MOVL R3,R8 7Copy byte count to R8 for 
;LOOP2 count 

MOVAL BUFFER, R7 ;Get buffer address in R7 

LOOP2: INCB (R7)+ ; Increment character 

SOBGTR R8,LOOP2 ;Until finished 

SOBGTR R5,LOOP1 ;Repeat LOOP1 until alphabet 
; complete 


The alphabet is now complete. Fall through LOOP1 and update the 
byte count so that it reflects the actual size of the last block 
written to tape. 


ADDL2 #2,R3 ;Update byte count 


The tape is now read, but first the program must perform one of 

the three functions described previously before the ACP allows 

read access. The program performs an ACP control function, 
specifying skip zero blocks. This is a special case of skip reverse 
and causes the ACP to allow read access. 


CLRL FIB+FIBSL_CNTRLVAL 7Set up to space zero blocks 
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MOVW #FIBSC_SPACE 

SQIOW_S CHAN=TAPECHAN, — 
FUNC=#I0$_ACPCONTROL, — 
P1=FIB_DESCR 

CMPW SSS_NORMAL, RO 

BSBW ERRCHECK 


, 
; Read the file 


, 


in reverse. 


,FIB+FIBSW_CNTRLFUNC ;Set up for space 


;function 

7Perform QIOW to tape channel 
;Perform an ACP control 
;function 

;Define the FIB 

; Success? 

;Find out 


MOVL #26,R5 ;Set up loop count 
MOVB #°A/Z/,R6 ;Get first character in R6 
LOOP3: 7 
MOVAL BUFFER, R7 ;And buffer address to R7 
SQIOW_S CHAN=TAPECHAN, — ;Channel is magtape 
FUNC=#1I0$_READVBLK! IOSM_REVERSE,- ;Function is read 
- ; reverse 
IOSB=IOSTATUS, - ;Define I/O status quadword 
P1=BUFFER, — ;And buffer address 
P2=R3 7R3 bytes 
CMPW #SSS_NORMAL, RO ; Success? 
BSBW ERRCHECK ;Find out 


a 


; Check the data read to verify that it 


a 


MOVL R3,R4 
CHECKDATA: 

CMPB (R7) +,R6 

BNEQ MISMATCH 

SOBGTR R4,CHECKDATA 

DECB R6 

ADDL2 2,R3 

SOBGTR R5,LOOP3 


; Now deaccess the file. 


SQIOW_S CHAN=TAPECHAN, -— 
FUNC=#10$_DEACCESS, - 
P1=FIB_DESCR, - 
IOSB=IOSTATUS 


; Deassign the channel and exit. 


EXIT: SDASSGN_S CHAN=TAPECHAN 


RET 
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matches the data written. 


7Copy R3 to R4 for loop count 

i 

7Check each character 

;If error, print message 
;Continue until finished 

7Go through alphabet in reverse 
;Update byte count by 2 for 
;next block 

;Read next block 


7Channel is magtape 
;Deaccess function 
;File information block 
;I/O status 


(required) 


;Deassign channel 
7Exit 


; If an error had been detected, 
; generate an error message here. 


; program simply exits. 


MISMATCH: 
BRB EXI 
ERRCHECK: 
BNEQ EXIT 
RSB 
END MAGI 


TAPE_EXAMPLE 


a program would normally 
But for this example the 


’ 


; Exit 


r 
;If not success, exit 
;Otherwise, return 
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4 Mailbox Driver 


The operating system supports a virtual device, called a mailbox, that is used for communication between 
processes. Mailboxes provide a controlled, synchronized method for processes to exchange data. Although 
mailboxes transfer information much like other I/O devices, they are not hardware devices. Rather, mailboxes 
are a software-implemented way to perform read and write operations between processes. 


The HP OpenVMS Programming Concepts and the HP OpenVMS System Services Reference Manual contain 
additional information about using mailboxes. 


4.1 Mailbox Operations 


This section describes the following mailbox operations: 
e Creating mailboxes 
e Deleting mailboxes 


e Protecting mailboxes 


4.1.1 Creating Mailboxes 


To create a mailbox and assign a channel and logical name to it, a process uses the Create Mailbox and Assign 
Channel ($CREMBX) system service. A logical name can optionally be associated with the mailbox. If a 
logical name is specified for the mailbox, the system enters the logical name in a logical name table and gives 
it an equivalence name of MBAn, where n is a unique unit number. 


$CREMBxX also establishes the characteristics of the mailbox. These characteristics include a protection 
mask, a permanence indicator, maximum message size, buffer quota, and direction in which I/O can be 
performed (read, write, or read/write). A mailbox is created as either temporary or permanent; both types 
require privilege to create. Applications and restrictions on how to use temporary and permanent mailboxes 
are described in the following sections. (Refer to the HP OpenVMS System Services Reference Manual for 
additional information on creating mailboxes.) 


Other processes can assign additional channels to a mailbox using either the $CREMBX or the Assign I/O 
Channel ($ASSIGN) system service. The mailbox is identified by its logical name both when it is created and 
when it is assigned channels by cooperating processes. Channels assigned to the mailbox can specify the 
direction that I/O can be performed on the channel. 
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Figure 4-1 shows the use of $CREMBX and $ASSIGN. 


Figure 4-1 Multiple Mailbox Channels 


User or 
system 
Process 


process 
creates 
mailbox. 


$CREMBX 
assigns 
channel. 


Cooperating 
processes use 
$ASSIGN or $CREMBX 
to define additional 
channels. 


Process Process 


ZK0676GE 


If sufficient dynamic memory for the mailbox data structure is not available when a mailbox is created, a 
resource wait occurs if resource wait mode is enabled. 


When a mailbox is created, a certain amount of space is specified for buffering messages that have been 
written to the mailbox but have not yet been read. The bufquo argument to the $CREMBX system service 
specifies this amount or quota. If that argument is omitted, its value defaults to the system parameter 
DEFMBXBUFQUO. 


A message written to a mailbox, in the absence of an outstanding read request, is queued to the mailbox, and 
the size of the message (the QIO P2 argument) is subtracted from the available buffering space. After the 
message is read, it is added back to the available buffering space. 


If a process attempts to write to a mailbox that is full or has insufficient buffering space and if the process has 
resource wait enabled (which is the default case), the process is placed in miscellaneous resource wait mode 
until sufficient space is available in the mailbox. If resource wait is not enabled, the I/O completes with the 
status return SS$- MBFULL in the I/O status block (IOSB). 


Channels can be assigned to mailboxes as bidirectional (read/write), read only, or write only. This allows for 
greater synchronization between users of the mailbox. To specify a unidirectional channel to the mailbox, 
specify the flags argument for the $CREMBX or $ASSIGN system services. 
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The flags argument is a longword bit mask that enables you to specify that the channel assigned to the 
mailbox is a read-only or write-only channel. If the flags argument is not specified, the default channel 
behavior is read/write. A channel assigned to the mailbox as read only is considered a reader. A channel 
assigned to the mailbox as write only is considered a writer. A channel assigned to the mailbox as read/write 
is considered both a reader and a writer. 


For the $ASSIGN system service, the $AGNDEF macro defines a symbolic name for each flag bit. These flags 
are as follows: 


e AGN$M_READONLY— When this flag is specified, $ASSIGN assigns a read-only channel to the mailbox 
device. An attempt to issue a $QIO WRITE operation on the mailbox channel causes an illegal I/O 
operation error. 


¢ AGN$M_WRITEONLY— When this flag is specified, $ASSIGN assigns a write-only channel to the 
mailbox device. An attempt to issue a $QIO READ operation on the mailbox channel causes an illegal I/O 
operation error. 


For the $CREMBX system service, the $CMBDEF macro defines a symbolic name for each flag bit. These 
flags are as follows: 


¢ CMB$M_READONLY— When this flag is specified, $CREMBX assigns a read-only channel to the 
mailbox device. An attempt to issue a $QIO WRITE operation on the mailbox channel causes an illegal 
I/O operation error. 


¢ CMB$M_WRITEONLY— When this flag is specified, $CREMBX assigns a write-only channel to the 
mailbox device. An attempt to issue a $QIO READ operation on the mailbox channel causes an illegal I/O 
operation error. 


Refer to the HP OpenVMS System Services Reference Manual for a syntax description of the $CREMBX and 
$ASSIGN system services. 


The programming examples at the end of this section (Section 4.5) show mailbox creation, interprocess 
communication, and synchronization. 


4.1.2 Deleting Mailboxes 


As each process finishes using a mailbox, it deassigns the channel using the Deassign I/O Channel 
($DASSGN) system service. Temporary mailboxes or permanent mailboxes that have been marked for 
deletion are actually deleted when no more channels are assigned to them. 


If a mailbox channel is deassigned, any incomplete I/O requests on the mailbox channel for the process 
deassigning the channel are removed. 


Permanent mailboxes that have not been marked for deletion must be explicitly deleted using the Delete 
Mailbox ($DELMBX) system service. An explicit deletion can occur at any time. As is true for temporary 
mailboxes, the mailbox is deleted when no processes have channels assigned to it. 


When a temporary mailbox is deleted, its message buffer quota is returned to the process that created it. (No 
quota charge is made for permanent mailboxes.) 


4.1.3. Mailbox Protection 


Mailboxes (both temporary and permanent) are protected by a code, or mask, that is similar to the code used 
in protecting volumes. As with volumes, four types of users (defined by UIC) can gain access to a mailbox: 
SYSTEM, OWNER, GROUP, and WORLD; however, only three types of access—logical I/O, read, and 
write—are meaningful to users of a mailbox. Therefore, when creating a mailbox, you can specify logical I/O, 
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read, and write access to the mailbox separately for each type of user. Logical I/O access is required for any 
mailbox operation. The set protection function modifier provides additional control of mailbox access (see 
Section 4.3.6). 


For additional information on temporary mailboxes and mailbox protection, see the description of the 
$CREMBxX system service in the HP OpenVMS System Services Reference Manual. 


4.1.4 Mailbox Message Format 


There is no standardized format for mailbox messages and none is imposed on users. 


4,2 Mailbox Driver Device Information 
You can obtain information on mailbox characteristics by using the Get Device/Volume Information 
($GETDVD system service. (Refer to the HP OpenVMS System Services Reference Manual.) 


$GETDVI returns mailbox characteristics when you specify the item code DVI$_DEVCHAR. Table 4-1 lists 
these characteristics, which are defined by the $DEVDEF macro. 


Table 4-1 Mailbox Characteristics 


Characteristic! Meaning 


Dynamic Bits (Conditionally Set) 


DEV$M_SHR Device is shareable. 
DEV$M_AVL Device is available. 
Static Bits (Always Set) 


DEV$M_REC Device is record-oriented. 
DEV$M_IDV Device is capable of input. 
DEV$M_ODV Device is capable of output. 
DEV$M_MBX Device is a mailbox. 


1. Defined by the $DEVDEF macro. 


DVI$_DEVCLASS and DVI$_DEVTYPE return the device class and device type names, which are defined by 
the $DCDEF macro. The device class for mailboxes is DC$_MAILBOX. The device type is DT$_MBX (or 
DT$_SHRMBxX if the mailbox is a shared memory mailbox). DVI$_DEVBUFSIZ returns the buffer size, which 
is the maximum message size in bytes. 


DVI$_DEVDEPEND returns a longword field in which the two low-order bytes contain the number of 
messages in the mailbox. (The two high-order bytes are not used and should be ignored.) 


DVI$_UNIT returns the mailbox unit number. Using mailbox to hold a termination message for a subprocess 
or a detached process requires that the parent process obtain this number to pass to the mbxunt argument of 
the $CREPRC system service. 
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4.3 Mailbox Function Codes 


The mailbox I/O functions are: 


e read 

e write 

e write end-of-file 

e set attention AST 

e wait for writer/reader 

e set protection 

e get mailbox information 


No buffered I/O byte count quota checking is performed on mailbox I/O messages. Instead, the byte count or 
buffer quota of the mailbox is checked for sufficient space to buffer the message being sent. The buffered I/O 
quota and AST quota are also checked. 


4.3.1 Read 


Read mailbox functions are used to obtain messages written to the mailbox. The operating system provides 
the following mailbox function codes: 


e JI0O$ READVBLK—Read virtual block 
e 10$_READLBLK—Read logical block 
e J10$_READPBLK—Read physical block 


IO0$_READLBLK, I0$_READVBLK, and IO$_READPBLK all perform the same operation. To issue a read 
request, a process can specify any of the read function codes. 


The following device- or function-dependent arguments are used with these codes: 


e P1—tThe starting virtual address of the buffer that is to receive the message. If P2 specifies a zero-length 
buffer, P1 is ignored. On OpenVMS Alpha and I64, P1 can be a 64-bit address. 


e P2—The size of the buffer in bytes (limited by the maximum message size for the mailbox). A zero-length 
buffer may be specified. If a message longer than the buffer is read, the alternate success status 
SS$_BUFFEROVF is returned in the I/O status block. In such cases, the message is truncated to fit the 
buffer. The driver does not provide a means for recovering the deleted portion of the message. 


The following function modifiers can be specified with a read request: 


¢ JO$M_WRITERCHECK—Completes the I/O operation with SS$_NOWRITER status if the mailbox is 
empty and no write channels are assigned to the mailbox. If no writer is assigned to the mailbox when the 
$QIO is issued and no data is in the mailbox, the $QIO completes immediately. If no data is in the 
mailbox but a writer is assigned, the $QIO operation completes when either a message is written or all 
writers deassign their channels to the mailbox. IO$M_WRITERCHECKX is ignored if the channel on 
which it is issued is read/write because a writer is always assigned. 


¢ IO$M_NOW—Completes the I/O operation immediately with no wait for a write request from another 
process. 
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¢ IO$M_STREAM—Ignores QIO record boundaries. The read operation transfers message data to the 
user's buffer until either P2 bytes are transferred, all message data currently in the mailbox is 
transferred, or an end-of-file message is encountered. If a WRITEOF message is within the records 
required to be read in order to fulfill the request for P2 bytes, the read request terminates successfully 
with the bytes it was able to read before finding the WRITEOF message and the end-of-file message 
becomes the first message in the mailbox. The next read request processes the end-of-file message. If the 
read request is a READ STREAM, then the request must be for greater than 0 bytes. $QIO READ 
STREAM can return fewer than P2 bytes with a return value of SS$_NORMAL if the mailbox is emptied 
by the $QIO READ STREAM request or a WRITEOF message is encountered. 
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Figure 4-2 shows $QIO READ STREAM operations. 


Figure 4-2 


1. 


$QIO READ STREAM Operation 


CREMBX 


WRITE 20 bytes 


READ (Record) 10 bytes 


WRITE 20 bytes 


READ STREAM 10 bytes 


WRITE 50 bytes 


READ STREAM 30 bytes 


Read (Record) 40 bytes 


Empty Mailbox 


|| 


Mailbox contains 1 record, 20 bytes long 


ai 


Empty Mailbox 


| | 


Mailbox contains 1 record, 20 bytes long 


| 


Mailbox contains 1 record, 10 bytes long 


mi 


Mailbox contains 2 records, 10 and 50 bytes long 


al 


Mailbox contains 1 record, 30 bytes long 


ai 


Empty Mailbox 


|| 


Diagram reflects state of Mailbox after specified operation has been performed. 
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A READ IO$M_STREAM (without IO$M_NOW specified) on an empty mailbox waits until some data has 
been written to the mailbox. It terminates with: 


— 0 bytes read if the next data written is an end-of-file message. 


— Fewer than P2 bytes read if the next data written is less than P2 bytes but greater than 0 bytes. 
(READ IO$M_STREAM ignores writes of 0 bytes.) 


— P2 bytes read if the next data written is greater than or equal to P2 bytes. 


If a $QIO READ STREAM is fulfilled by multiple $QIO WRITE requests, the sender PID returned in the 
IOSB of the $QIO READ STREAM reflects the first write request. A $QIO READ STREAM is charged 
BUFQUO for the request. This BUFQUO is released when the read request is met. A $QIO READ 
STREAM request that would cause BUFQUO to be exceeded for the mailbox when the mailbox has no 
writes pending returns an SS$_EXQUOTA error. 


A $QIO READ STREAM issued to a mailbox that would cause BUFQUO to be exceeded because 
BUFQUDO is occupied by write requests still executes. This happens because by allowing the mailbox to 
temporarily exceed BUFQUO, BUFQUO is freed. Similarly, a $QIO WRITE that is issued to a mailbox 
that would cause BUFQUO to be exceeded, because the BUFQUO is occupied by read stream requests, 
still executes. 


Reads of 0 bytes are handled differently depending on which functional modifiers are specified. If 
IO$M_STREAM is specified, then the $QIO returns SS$_NORMAL with 0 bytes read. The contents of the 
mailbox remain exactly as they were before the $QIO was issued. A $QIO READ STREAM of 0 bytes does not 
remove a 0 byte record, nor does it remove an end-of-file marker. If IO$M_STREAM is not specified, then 
$QIO returns one of the following: 


e SS$ NORMAL (if 0 bytes were written with the corresponding $QIO WRITE performed) 
e SS$_BUFFEROVKE (if the corresponding $QIO WRITE wrote more than 0 bytes with 0 bytes read) 
e SS$ _ENDOFFILE (if a WRITEOF function was performed as the corresponding $QIO write function) 


For a 0-byte nonstream read, a record is actually removed from the mailbox to meet the $QIO READ request. 
Note that the use of the word “immediately” does not imply that synchronization of the $QIO request should 
not be performed. 
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Figure 4-3 shows the read mailbox functions. In this figure, Process A reads a mailbox message written by 
Process B. As the figure indicates, a mailbox read request requires a corresponding mailbox write request 
(except in the case of an error). The requests can be made in any sequence; the read request can either 
precede or follow the write request. 


Figure 4-3 Read Mailbox 
QrQ Oer® 
Read QIO Write QIO 
aK |-E 


Data Data 


®) @) 


Note: Numbers indicate order of events. 
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If Process A issues a read request before Process B issues a write request, one of two events can occur. If 
Process A did not specify the function modifier IO$M_NOW, Process A's request is queued before Process B 
issues the write request. When Process B's write request occurs, the data is transferred from Process B, 
through the system buffers, to Process A to complete the I/O operation. 


However, if Process A did specify the IO$M_NOW function modifier, the read operation is completed 
immediately. That is, no data is transferred from Process B to Process A, and Process A's request is not 
queued until Process B issues the write request. In this case, the I/O status returned to Process A is 
SS$_ENDOFFILE. 


If Process B sends a message (with no function modifier; see Section 4.3.2) before Process A issues a read 
request (with or without a function modifier), Process A finds a message in the mailbox. The data is 
transferred and the I/O operation is completed immediately, regardless of whether IO$M_NOW is specified on 
the read request. 


4.3.2 Write 


Write mailbox functions are used to transfer data from a process to a mailbox. The operating system provides 
the following mailbox function codes: 


¢ 10$_WRITEVBLK—Write virtual block 
¢ 10$_WRITELBLK—Write logical block 
¢ I0$_WRITEPBLK—Write physical block 
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10$_WRITEVBLK, IO$_WRITELBLK, and IO0$_WRITEPBLK all perform the same operation. To issue a 
write request, a process can specify any of the write function codes. 


These function codes take the following device- or function-dependent arguments: 


e P1—tThe starting virtual address of the buffer that contains the message being written. If P2 specifies a 
zero-length buffer, P1 is ignored. On OpenVMS Alpha and I64, P1 can be a 64-bit address. 


e P2—The size of the buffer in bytes (limited by the maximum message size for the mailbox). A zero-length 
buffer produces a zero-length message to be read by the mailbox reader. 


The following function modifiers can be specified with a write request: 


¢ IO$M_READERCHECK—Completes the I/O operation immediately, with SS$_NOREADER status, if no 
read channels are assigned to the mailbox. If a $QIO WRITE with IO$M_READERCHECK is issued and 
is outstanding and all read channels assigned to the mailbox are then deassigned, the $QIO completes 
with SS$_NOREADER status. IO$M_READERCHECK is ignored if the channel on which it is issued is 
bidirectional read/write, because there is always a reader assigned. If SS$_NOREADER is returned for a 
write request, the $QIO WRITE operation does not place any data in the mailbox. If SS$_NOREADER is 
returned for a write end-of-file message request, the $QIO WRITE operation does not place the end-of-file 
marker in the mailbox. 


¢ IO$M_NOW—Completes the I/O operation immediately without waiting for another process to read the 
mailbox message. $QIO WRITE, without IO$M_NOW specified, does not complete until the data is read. 
$QIO WRITE NOW completes when the data is in the mailbox. If both IO$¢M_READERCHECK and 
IO$M_NOW are specified and no read channel is assigned to the mailbox, a status of SS$_NOREADER is 
returned and the data is not placed in the mailbox. If a read channel is assigned, the 
IO$M_READERCHECK modifier is ignored. 


¢ IO$M_NORSWAIT—If the mailbox is full, the I/O operation fails with a status return of SS$_MBFULL 
rather than placing the process in resource wait mode. Note that IO$M_NORSWAIT does not disable 
resource waits that may occur elsewhere in the $QIO operation. For example, IO$M_NORSWAIT does not 
affect any resource waiting that occurs when I/O processing routines try to allocate an I/O request packet 
while passing the I/O request to the mailbox driver. 


A $QIO WRITE of 0 bytes causes a 0-byte long message to be placed in the mailbox. When this data is read by 
a $QIO READ without IO$M_STREAM specified, the $QIO READ returns an SS$_NORMAL status and 0 
bytes. When this data is read by a $QIO READ STREAM in an attempt to read P2 bytes (P2 being greater 
than 0), the data is ignored. However, a $QIO READ STREAM of 0 bytes has no effect on the mailbox. A $QIO 
WRITE READERCHECK of 0 bytes, when no read channel is assigned to the mailbox, returns an 
SS$_NOREADER error and the 0-byte record is not placed in the mailbox. A message that is 0 bytes long is 
charged 1 byte of mailbox BUFQUO. 


Figure 4-4 shows the write mailbox function. In this figure, Process A writes a message to be read by Process 
B. As in the read request example, a mailbox write request requires a corresponding mailbox read request 
(unless an error occurs) and the requests can be made in any sequence. 


If Process A issues a write request before Process B issues a read request, one of two events can occur. If 
Process A did not specify the function modifier IO$M_NOW, Process A's write request is queued before 
Process B issues a read request. When this request occurs, the data is transferred from Process A to Process B 
to complete the I/O operation. 


However, if Process A did specify the IO$M_NOW function modifier, the write operation is completed 
immediately. The data is available to Process B and is transferred when Process B issues a read request. 
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If Process B issues a read request (with no function modifier) before Process A issues a write request (with or 
without the function modifier), Process A finds a request in the mailbox. The data is transferred and the I/O 
operation is completed immediately. 


Figure 4-4 Write Mailbox 
Or-® Oxe@® 
Write QIO Read QIO 
Process F Process 
[+= 
Data Data 


® oC 


Note: Numbers indicate order of events. 
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4.3.3 Write End-of-File Message 


Write end-of-file message functions are used to insert a special message in the mailbox. The process that 
reads the end-of-file message is returned the status code SS$_ENDOFFILE in the I/O status block. The 
message count of the Get Mailbox Information function reflects this end-of-file message; however, the mailbox 
byte count of this function does not include end-of-file markers. An end-of-file message is charged 1 byte of 
mailbox BUFQUO. 


This function takes no arguments. The operating system provides the following function code: 


10$_WRITEOF—Write end-of-file message 


The following function modifiers can be specified with a write end-of-file request: 


¢ IO$M_READERCHECK—Completes the I/O operation immediately, with SS$_NOREADER status, if no 
read channels are assigned to the mailbox. If a $QIO WRITEOF with IO$M_READERCHECK is issued 
and is outstanding and all read channels assigned to the mailbox are then deassigned, the $QIO 
completes with SS$_NOREADER status. IO$M_READERCHECK is ignored if the channel on which it is 
issued is bidirectional read/write, because there is always a reader assigned. If SS$_NOREADER is 
returned for a write end-of-file message request, the $QIO WRITEOF operation does not place the 
end-of-file marker in the mailbox. 


¢ IO$M_NOW—Completes the I/O operation immediately without waiting for another process to read the 
mailbox message. If both IO$M_READERCHECK and IO$M_NOW are specified, and no read channel is 
assigned to the mailbox, a status of SS$_NOREADER is returned and the end-of-file message is not 
placed in the mailbox. 
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¢ IO$M_NORSWAIT—If the mailbox is full, the I/O operation fails with a status return of SS$_MBFULL 
instead of placing the process in resource wait mode. Note that IO$M_NORSWAIT does not disable 
resource waits that may occur elsewhere in the $QIO operation. For example, IO$M_NORSWAIT does not 
affect any resource waiting that occurs when I/O processing routines try to allocate an I/O request packet 
while passing the I/O request to the mailbox driver. 


4.3.4 Set Attention AST 


Set attention AST functions specify that an asynchronous system trap (AST) be delivered to the requesting 
process in the following cases: 


e When a cooperating process places a read request for which no write request is pending in a designated 
mailbox. This is called an unsolicited read request. 


e When a cooperating process places a write request for which no read request is pending in a designated 
mailbox. This is called an unsolicited write request. 


e When room becomes available in the mailbox. 


If a message exists in the mailbox when a request to enable a write attention AST is issued, the AST routine 
is activated immediately. If no message exists, the AST is delivered when a write request message arrives; 
therefore, the requesting process need not repeatedly check the mailbox status. You must have both logical 
I/O and read access to the mailbox prior to performing a set attention AST function. 


The operating system provides the following function codes: 

e 10$ SETMODE!IO$M READATTN—Read attention AST 

e 10O$ SETMODE!IO$M WRTATTN—Write attention AST 

e JO$ SETMODE!IO$M MB ROOM NOTIFY—Room in the mailbox attention AST 

These function codes take the following device- or function-dependent arguments: 

e P1—AST address (request notification is disabled if the address is 0) 

e P2—AST parameter returned in the argument list when the AST service routine is called 
e P38—Access mode to deliver AST; maximized with requester's mode 


These functions are enabled only once; they must be explicitly reenabled after the AST has been delivered if 
you desire repeat notification. All types of enable functions, and more than one of each type, can be set at the 
same time. The number of enable functions is limited only by the AST quota for the process. 
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Figure 4-5 shows the write attention AST function. In this figure, an AST is set to notify Process A when 
Process B sends an unsolicited message. 


Figure 4-5 Write Attention AST (Read Unsolicited Data) 
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Process A uses the IO$_SETMODE!IO$M_WRTATTN function to request an AST. When Process B sends a 
message to the mailbox, the AST is delivered to Process A. Process A responds to the AST by issuing a read 
request to the mailbox. The data is then transferred to complete the I/O operation. 


If several requesting processes have set ASTs for unsolicited messages at the same mailbox, all ASTs are 
delivered when the first unsolicited message is placed in the mailbox; however, only the first process to 
respond to the AST with a read request receives the data. Therefore, when the next process to respond to an 
AST issues a read request to the mailbox, it might find the mailbox empty. If this request does not include the 
function modifier IO$M_NOW, it is queued before the next message arrives in the mailbox. 
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Figure 4-6 shows the read attention AST function. In this figure, an AST is set to notify Process A when 
Process B issues a read request for which no message is available. 


Figure 4-6 Read Attention AST 
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Process A uses the IO$_SETMODE!IO$M_READATTN function to specify an AST. When Process B issues a 
read request to the mailbox, the AST is delivered to Process A. Process A responds to the AST by sending a 
message to the mailbox. The data is then transferred to complete the I/O operation. 


If several requesting processes set ASTs for read requests for the same mailbox, all ASTs are delivered when 
the first read request is placed in the mailbox. Only the first process to respond with a write request is able to 
transfer data to Process B. 


4.3.5 Wait for Writer/Reader 


The wait for writer/reader mailbox driver function waits until a channel is assigned to the mailbox with the 
requested access direction. This function returns immediately if a channel is already assigned to the mailbox 
with the proper access direction. This function always returns immediately if issued on a bidirectional 
mailbox channel. Any channel assigned bidirectionally to the mailbox satisfies both types of wait requests. 


The wait function requires the same synchronization techniques as all other $QIO functions. $QIO Wait 
should not be issued without any synchronization of its completion. If no synchronization is performed, the 
program behaves as if no $QIO Wait function had been issued (except for the small delay caused by issuing 
the $QIO Wait). 


The following function codes and modifiers are provided: 
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¢ 10$_SETMODE!IO$M_READERWAIT—Waits for a read channel to be assigned to the mailbox. 
¢ I10$_SETMODE!IO$M_WRITERWAIT—Waits for a write channel to be assigned to the mailbox. 
These function codes require no function-dependent arguments. 


These functions are enabled only once. Once the $QIO operation completes, these functions must be explicitly 
reenabled. 


4.3.6 Set Protection 


The set protection functions allow the user to set volume protection on a mailbox (see Section 4.1.3). The 
requester must either be the owner of the mailbox or have BYPASS privilege. The OpenVMS operating 
system provides the following function code: 


10$_SETMODE!IO$M_SETPROT—Set protection 


This function code takes the following device- or function-dependent argument: 


P2—A volume protection mask 


The protection mask specified by P2 is a 16-bit mask with 4 bits for each class of owner: SYSTEM, OWNER, 
GROUP, and WORLD, as shown in Figure 4-7. 


Figure 4-7 Protection Mask 
15 11 7 
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Only logical I/O, read, and write functions have meaning for mailboxes. A clear (0) bit implies that access is 
allowed. If P2 is 0 or unspecified, the mask is set to allow all read, write, and logical operations. 


The I/O status block for the set protection function (see Figure 4-10 ) returns SS$_NORMAL in the first word 
if the request was successful. If the request was not successful, the $QIO system service returns 
SS$_NOPRIV and both longwords of the I/O status block are returned as zeros. 

4.3.7 Get Mailbox Information 


The get mailbox information function allows the user to find out the number of unread messages and bytes in 
the mailbox. The following function code is provided: 
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IO$_ SENSEMODE—Get mailbox contents information 


The following function codes and modifiers are provided: 


e JO$ SENSEMODE!IO$M_READERCHECK—If a $QIO SENSEMODE with IO$M_READERCHECK is 
issued and no read channels are assigned to the mailbox, then the SS$_NOREADER condition value is 
returned in the IOSB. 


e J0$ SENSEMODE!IO$M_WRITERCHECK—If a $QIO SENSEMODE with IO$M_WRITERCHECK is 
issued and no write channels are assigned to the mailbox, then the SS$_NOWRITER condition value is 
returned in the IOSB. 


These function codes require no function-dependent arguments. 


4.4 V/O Status Block 


»The I/O status blocks (IOSB) for mailbox read, write, set protection, and get mailbox information QIO 
functions are shown in Figures Figure 4-8, Figure 4-9, Figure 4-10, and Figure 4-11. 


Appendix A lists the I/O status returns for these functions. In addition to the IOSB return values, the 
following statuses can be returned in RO by the call to the system service: 


SS$_ACCVIO 
SS$_EXQUOTA 
SS$_ILLIOFUNC 
SS$_INSFMEM 
SS$_MBFULL 
SS$_MBTOOSML 
SS$_NOPRIV 
SS$_NORMAL 
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(The OpenVMS system messages documentation provides explanations and suggested user actions for both 
types of returns.) 


Figure 4-8 IOSB Contents — Read Function 
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Figure 4-9 IOSB Contents— Write Function 
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Figure 4-10 IOSB Contents— Set Protection Function 
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Figure 4-11 IOSB Contents — Get Mailbox Information Function 
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4.5 Mailbox Driver Programming Examples 
This section contains the following programming examples: 


e Example 4-1 shows a MACRO382 program that creates a mailbox and puts mail into it. 
e Example 4-2 assigns a read-only channel to the mailbox. 
e Example 4-3 assigns a write-only channel to the mailbox. 


Example 4-1 creates a mailbox and puts mail into it; no matching read is pending on the mailbox. First, the 
program shows that if the function modifier IO$M_NOW is not used when mail is deposited, the write 
function waits until a read operation is performed. In this case, IO$M_NOW is specified and the program 
continues after the mail is left in the mailbox. 


Next, the mailbox is read. If there is no mail in the mailbox, the program waits because IO$M_NOW is not 
specified. IO$M_NOW should be specified if there is any doubt about the availability of data in the mailbox, 
and it is important for the program not to wait. 


It is up to the user to coordinate the data that goes into and out of mailboxes. In this example, the process 
reads its own message. Normally, two mailboxes are used for interprocess communication: one for sending 
data from process A to process B, and one for sending data from process B to process A. If a program is 
arranged in this manner, there is no possibility of a process reading its own message. 


NOTE The table for temporary mailbox names can be redfined to be a group table. This allows the 
processes in other jobs with same group number to use the samelogical name to access the 
mailbox. For example, LYM$TEMPORARY_MAILBOxX can be redefined to any shareable table 
that the process has write access to. In this case, it could be redefined to LNM$GROUP if the 
process has GRPNAM privlege or if the group table allows the process to write to it. See the 
description of the $CREMBX service in the System Services Reference Manual for more 
information. 


Example 4-2 and Example 4-3 work together from two separate processes and show the unidirectional 
mailbox synchronization features. With the default definition of LNM$TEMPORARY_MAILBOxX, the logical 
name for the mailbox is created in the job logical name table. The processes running both example programs 
should be in the same job. 


Example 4-2 performs the following functions: 
1. Assigns a read-only channel to the mailbox. 
2. Waits for another program to assign a writable channel to the mailbox. 


3. Reads, using the IO$M_WRITERCHECK function modifier, what has been written to the mailbox. Each 
record is echoed to SYS$OUTPUT. 


4. When SS$_NOWRITER is returned from the read operation, goes back to Step 2 and waits for another 
writer. 


Example 4-3 is a writer to the mailbox. It performs the following functions: 
1. Assigns a write-only channel to the mailbox. 
2. Waits for a reader. 


3. Gathers user input until the user enters Ctrl/Z, then writes that input to the mailbox. 
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Example 4-1 Mailbox Driver Program Example 1 


KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK 


-TITLE MAILBOX DRIVER PROGRAM EXAMPLE 
-IDENT /01/ 


; Define necessary symbols. 


SIODEF ;Define I/O function codes 


; Allocate storage for necessary data structures. 


; Allocate output device name string and descriptor. 


DEVICE_DESCR: i 


. LONG 20$-10$ ;Length of name string 

. LONG 10$ ;Address of name string 
10S: -ASCII /SYSSOUTPUT/ ;Name string of output device 
208: ;Reference label 


; Allocate space to store assigned channel number. 


DEVICE_CHANNEL: ; 
. BLKW 1 ;Channel number 


, 
; Allocate mailbox name string and descriptor. 


, 


MAILBOX_NAME: ; 


. LONG ENDBOX-NAMEBOX ;Length of name string 
. LONG NAMEBOX ;Address of name string 
NAMEBOX: .ASCII /146_MAIN_ST/ ;Name string 
ENDBOX: ;Reference label 


, 
; Allocate space to store assigned channel number. 


a 


MATLBOX_CHANNEL: ; 
. BLKW 1 ;Channel number 


, 
; Allocate space to store the outgoing and incoming messages. 


a 


IN_BOX_BUFFER: ; 
. BLKB 40 7Allocate 40 bytes for 
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; received message 
IN_LENGTH=.-—-IN_BOX_BUFFER ;Define input buffer length 


OUT_BOX_BUFFER: ; 


-ASCII /SHEEP ARE VERY DIM/ ;Message to send 
OUT_LENGTH=.-OUT_BOX_BUFFER ;Define length of message to 
;send 


, 
; Finally, allocate space for the I/O status quadword. 


a 


STATUS: ; 
. QUAD 1 ;I/O status quadword 


KKK KKK KK KKK KKK KK KKK KK KK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KK KKK KKK KKK KKK 


i Start Program 


KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KK KKK 


; The program first creates a mailbox and assigns a channel to the 

; process output device. Then a message is placed in the mailbox and 
7; a message is received from the mailbox (the same message). Finally, 
; the program prints the contents of the mailbox on the process output 
; device. 


START: .» WORD 0 ;Entry mask 

SCREMBX_S CHAN=MAILBOX_CHANNEL,- ;Channel is the mailbox 
PROMSK=#*X0000, - ;No protection 
BUF QUO=#*X0060, - ;Buffer quota is hex 60 
LOGNAM=MATLBOX_NAME, — ;Logical name descriptor 
MAXMSG=#*X0060 ;Maximum message is hex 60 

CMPW SSS$_NORMAL, RO ;Successful mailbox creation? 

BSBW ERROR_CHECK ;Find out 

SASSIGN_S —- ;Assign channel 
DEVNAM=DEVICE_DESCR, -— ;Device descriptor 
CHAN=DEVICE_CHANNEL ;Channel 

CMPW SSS_NORMAL, RO 7Successful channel assign? 

BSBW ERROR_CHECK ;Find out 


; The program now writes to the mailbox using a write request that 

; includes the function modifier IOSM_NOW so that it need not wait for 
; a read request to the mailbox before continuing to the next step in 
; the program. 


SQIOW_S FUNC=#IOS_WRITEVBLK! IOSM_NOW,- ;Write message NOW 


CHAN=MATLBOX_CHANNEL, - ;to the mailbox channel 
P1=OUT_BOX_BUFFER, -— ;Write buffer 
P2=#OUT_LENGTH ;Buffer length 
CMPW SSS_NORMAL, RO , Successful write request? 
BSBW ERROR_CHECK ;Find out 
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, 
; Read the mailbox. 


, 


SQIOW_S FUNC=#I0O$_READVBLK, ;Read the message 
CHAN=MAILBOX_CHANNEL,- ;in the mailbox channel 
IOSB=STATUS, - ;Define status block to 
- ;receive message length 
P1=IN_BOX_BUFFER, — ;Read buffer 
P2=#IN_LENGTH ;Buffer length 

CMPW SSS_NORMAL, RO ;Successful read request? 

BSBW ERROR_CHECK ;Find out 


; The program now determines how much mail is in the mailbox (this 
; information is in STATUS+2) and then prints the mailbox message on 
; the process output device. 


MOVZWL STATUS+2,R2 7Byte count into R2 

SQIOW_S FUNC=#1I0$_WRITEVBLK, — ;Write function to the 
CHAN=DEVICE_CHANNEL, — ;output device channel 
P1=IN_BOX_BUFFER, -— ;Address of buffer to write 
P2=R2,- ;How much to write 
P4=#32 ;Carriage control 


; Finally, deassign the channel and exit. 


EXIT: SDASSGN_S CHAN=DEVICE_CHANNEL ;Deassign channel 
RET ,;Return 


; This is the error-checking part of the program. Normally, some kind 
; of error recovery would be attempted at this point if an error was 
; detected. However, this example program simply exits. 


ERROR_CHECK: r 
BNEQ EXIT ;System service failure, exit 
RSB ;Otherwise, return 
. END START 


Example 4-2 assigns a read-only channel to the mailbox. 


Example 4-2 Mailbox Driver Program Example 2 


* MATLBOX_READER.C 

* C program to demonstrate features of the Mailbox driver. 

* This program is a Mailbox READER. It assigns a READ_ONLY channel to the 
* mailbox. Its partner program is a Mailbox WRITER. 

* Compile with Compaq C on VAX or Alpha systems: * $ CC MAILBOX_READER * S$ LINK MATLBOX_READER 
ae 

#include <stdio.h> /* Standard C I/O */ 

#include <descrip.h> /* Descriptor structure definitions */ 
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#include <libSroutines.h> /* LIBS RTL function definitions */ 

#include <starlet.h> /* System service definitions */ 

#include <ssdef.h> /* System Service status code definitions */ 
#include <cmbdef.h> /* CREMBX definitions */ 

#include <efndef.h> /* Event Flag definitions */ 

#include <iodef.h> /* I/O definitions */ 


#define SARRAY_DESCRIPTOR(name,size,array_name) \ 
static char array_name[ size ]; \ 
struct dsc$descriptor_s name = \ 
{ size, DSCSK_DTYPE_T, DSCSK_CLASS_S, array_name } 
int main (void) 
{ 
/* 
* Message limits are intentionally small to facilitate demonstration of 
* error conditions. 


Sf: 
#define max_msg_len 64 /* Maximum output string size ef 
#define mailbox_maxmsg 64 /* Maximum mailbox message size */ 
#define mailbox_bufquo 128 /* Total buffer space in mailbox */ 


SDESCRIPTOR (mailbox_name_desc, "MATLBOX_EXAMPLE") ; 
SDESCRIPTOR(EOF_string_desc, 

"End of file read ... waiting for another WRITER"); 
SARRAY_DESCRIPTOR (read_buffer_desc,max_msg_len, read_buffer) ; 


#pragma member_alignment save 
#pragma nomember_alignment LONGWORD 


struct io_status_block { /* I/O status block */ 
unsigned short int condition; 
unsigned short int count; 
unsigned int dev; 
} iosb; 
#pragma member_alignment restore 


int status, mailbox_channel; 


/* 
* Create a temporary mailbox with a READONLY channel. Its logical name 
* will be entered into the LNMSTEMPORARY_MATILBOX logical name table. 
*/ 


status = sysScrembx (0, &mailbox_channel,mailbox_maxmsg,mailbox_bufquo, 
0,0, &mailbox_name_desc, CMBSM_READONLY) ; 
if (status != SSS$_NORMAL) 


(void) libS$signal (status); 


/* 
* Mark the mailbox for deletion. This step is not necessary for a temporary 
* mailbox, but is included as an illustration. 
fF 
(void) sysSdelmbx (mailbox_channel); 
/* 
* Loop forever, first waiting until a WRITE channel is assigned to the mailbox 
* and then reading data from it until the WRITER deassigns. 
*/ 
while (TRU 
{ 


ES | 
~~ 
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/* First, check to see if there is a WRITER assigned to the mailbox */ 
status = sysS$qiow ( 


EFNSC_ENF, 
mailbox_channel, 
IO$_SENSEMODE | lO$M_WRITERCHECK, 


&iosb, 
0,0, 
0,0,0,0,0,0); 


/* If there was no WRITER, then wait for one.*/ 


Lf 


((unsigned int) iosb.condition == SSS_NOWRITER) 


status = sys$qiow( 


/* 


EFNSC_ENF, 

mailbox_channel, 

IO$_SETMODE | IO$M_WRITERWAIT, 
&iosb, 

0,0, 

0,0,0,0,0,0); 


* While the status is good, READ from the mailbox, and echo the 
* data to SYSSOUTPUT. 


uA 


while (status == SS$_NORMAL) 


{ 


status = sysSqiow( 
EFNSC_ENF, 
mailbox_channel, 
IO$_READVBLK | IOSM_WRITERCHECK, 
&1iosb, 
0,0, 
read_buffer_desc.dscSa_pointer,max_msg_len, 
0,0,0,0); 
if (status != SSS_NORMAL) 
(void) libSsignal (status) ; 
status = iosb.condition; 


if (status == SSS_NORMAL) 


read_buffer_desc.dsc$w_length = iosb.count; 
(void) libSput_output (&read_buffer_desc) ; 


else if (status == SSS_ENDOFFILE) 


(void) libSput_output (&EOF_string_desc) ; 


Example 4-3 assigns a write-only channel to the mailbox. 


Example 4-3 


/ 


+ + FF F 


Mailbox Driver Program Example 3 


MAILBOX_WRITER.C 
C program to demonstrate features of the Mailbox driver. 
This program is a Mailbox WRITER. It assigns a WRITE_ONLY channel to the 


mailbox. 


It's partner program is a Mailbox READER. 
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* Compile with Compaq C on VAX or Alpha systems: 
* §$ CC MAILBOX_WRITER 
* §$ LINK MAILBOX_WRITER 


*/ 

include <stdio.h> /* Standard C I/O */ 

include <descrip.h> /* Descriptor structure definitions */ 
include <lib$routines.h> /* LIBS RTL function definitions */ 
include <rmsdef.h> /* RMS status code definitions */ 
include <starlet.h> /* System service definitions */ 
include <ssdef.h> /* System Service status code definitions */ 
include <cmbdef.h> /* CREMBX definitions */ 

include <efndef.h> /* Event Flag definitions */ 

include <iodef.h> /* I/O definitions */ 

define S$ARRAY_DESCRIPTOR(name,size,array_name) \ 


static char array_name[ size ]; \ 
struct dscSdescriptor_s name = \ 
{ size, DSCSK_DTYPE_T, DSCS$K_CLASS_S, array_name } 


void enable_room_ast (int mailbox_channel, int efn); 
void more_room_ast (int efn); 


volatile int ast_enabled = FALSE; 

int main(void) 

{ 

/* 
* Message limits are intentionally small to facilitate demonstration of 
* error conditions. 


*/ 
#define max_msg_len 128 /* Maximum input string size */ 
#define mailbox_maxmsg 64 /* Maximum mailbox message size */ 
#define mailbox_bufquo 128 /* Total buffer space in mailbox */ 


SDESCRIPTOR (mailbox_name_desc, "MAITLBOX_EXAMPLE") ; 
SDESCRIPTOR(prompt_string_desc, 

"DATA TO SEND TO MAILBOX (<CTRL Z> to terminate) >>>"); 
SARRAY_DESCRIPTOR (write_buffer_desc,max_msg_len,write_buffer) ; 


#pragma member_alignment save 
#pragma nomember_alignment LONGWORD 
struct io_status_block { /* I/O status block */ 
unsigned short int condition; 
unsigned short int count; 
unsigned int dev; 
} iosb; 
#pragma member_alignment restore 


int status, mailbox_channel, wait_efn; 


/* 

* Create a temporary mailbox with a WRITEONLY channel. Its logical name 
* will be entered into the LNMSTEMPORARY_MATLBOX logical name table. 

uA 


status = sysS$crembx (0, &mailbox_channel,mailbox_maxmsg,mailbox_bufquo, 
0,0, &mailbox_name_desc, CMBSM_WRITEONLY) ; 
if (status != SSS_NORMAL) (void) libSsignal (status); 
/* 
* Mark the mailbox for deletion. This step is not necessary for a temporary 


* mailbox, but is included as an illustration. 
*/ 


(void) sys$delmbx (mailbox_channel) ; 
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/* 
* Reserve an event flag to use with "room in malbox" AST notifications. 
*/ 
status = libSget_ef (&wait_efn); 
if (status != SS$_NORMAL) 
(void) libSsignal (status); 
/* 


* Loop forever, first waiting until a READ channel is assigned to the mailbox 
* and then write data until there is no more data to write. 
*/ 
while (TRUE) 
{ 
/* 
* Wait for a READER to assign a channel. If a READER is already 
* assigned, this will return immediatly. 
*/ 
status = sysSqiow ( 
EFNSC_ENF, 
mailbox_channel, 
IO0$_SETMODE | IOSM_READERWAIT, 
&iosb, 
0,0, 
0,0,0,0,0,0); 
while (status) 
{ 
write_buffer_desc.dsc$w_length = max_msg_len; 
status = libS$Sget_input ( 
&write_buffer_desc, 
é&prompt_string_desc, 
éwrite_buffer_desc.dsc$w_length) ; 


If at end of file (user typed <CTRL Z>) then write EOF to 

the mailbox, deassign the channel, and exit. 

The writer should not deassign the channel while the write EOF 
operation is pending, since the write would be cancelled and 
the reader would never receive the EOF. Omitting IOSM_NOW in 
this QIOW insures that it will not complete until the reader 

* has actually read the EOF from the mailbox. 


if (status == RMSS_EOF) 


(void) sysSqiow ( 
EFNSC_ENF, 
mailbox_channel, 
IO$_WRITEOF | IOSM_READERCHECK, 
&iosb, 
0, 0). 0,0) 
00,0, 0) 3 
(void) sysS$dassgn(mailbox_channel) ; 
(void) sysSexit (SS$_NORMAL) ; 


~ 


Write the message into the mailbox. If there isn't enough 
room, try again until it fits. 

Note that if the NORSWAIT function modifier had been eliminated 
below, then the ROOM_NOTIFY and the retry loop could have been 
removed. ROOM_NOTIFY was used in this example simply to show 
its use. It would be more appropriately used when the program 
has other things it can be working on, as opposed to the 
example below in which the program is not doing anything except 
WAITING for room in the mailbox. 


+ * + FF FF F F F F F 
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} 


do 
{ 
status = sysSqiow ( 
EFNSC_ENF, 
mailbox_channel, 
IO$_WRITEVBLK | IO$SM_READERCHECK | IOSM_NoW| IO$M_NORSWAIT, 
&iosb, 
0, Oy 
write_buffer_desc.dscSa_pointer, 
write_buffer_desc.dsc$w_length, 
0,0;0;,0)3 
if (status == SS$_NORMAL) 
{ 
/* If there is no longer a reader, just exit. */ 
if ((unsigned int) iosb.condition == SSS$_NOREADER) 
{ 
(void) sysS$dassgn(mailbox_channel) ; 
(void) sysSexit (iosb.condition) ; 
} 
} 
else if (status == SSS$_MBFULL) 
{ 
if (ast_enabled) 
/* 
* Wait here until the AST routine sets the event 
* flag. A read might have already occured, in which 
* case the wait will return immediately. 
*/ 
(void) sysSwaitfr(wait_efn); 
else 
/* 
* The mailbox was full a moment ago at the time of 
* write, but a read might have already occured and 
* the mailbox might be empty now. It is possible 
* that no more reads will complete (and deliver 
* the AST) before the next write. So enable the AST 
* and try the write one more time before waiting for 
* the event flag. 
*/ 
enable_room_ast (mailbox_channel, wait_efn); 
} else /* An unexpected error condition */ 
(void) libSsignal (status) ; 
} 
while (status != SS$_NORMAL) ; 


void enable_room_ast (int mailbox_channel, int efn) 


/* 


* This routine requests AST delivery when there is room in the mailbox. 


* AST delivery may be triggered by a read or a cancelled I/O. 


*/ 
{ 
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int status; 


ast_enabled = TRUE; 


status 


sys$clref (efn); 


This QIOW returns immediately, whether there is room in the mailbox 
or not. Even if there is room in the mailbox now, the AST is 

NOT delivered immediately, but only later when a read or cancel 

I/O occurs on the mailbox. 
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status = sysS$qiow( 
EFNSC_ENF, 
mailbox_channel, 
IO$_SETMODE | IOSM_MB_ROOM_NOTIFY, 
0,0,0, 
more_room_ast,efn,0,0,0,0); 
} 
void more_room_ast (int efn) 
/* 
* This AST routine is called when there is room to write more data into 
* the mailbox. 
*/ 
{ 
ast_enabled = FALSE; 
(void) sysS$setef(efn); 
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5 Terminal Driver 


This chapter describes the use of the terminal driver (TTDRIVER) and the LAT port driver (LTDRIVER). The 
terminal driver supports the asynchronous, serial line multiplexers listed in Table 5-1. The terminal driver 
also supports the console terminal. The LAT port driver accommodates I/O requests from application 
programs; for example to make connections to remote devices, such as a printer, on a server (see Section 
5.4.4). 


5.1 Supported Terminal Devices 


In addition to the multiplexers listed in Table 5-1, the terminal driver supports serial line interfaces. At least 
one such interface is always provided and is used to attach the system console terminal. This interface does 
not allow the setting of multiple terminal speeds, parity, or any maintenance functions, with the exception of 
the interface included with the VAX 8200 processor. The terminal devices supported by the operating system 
for this interface are listed in Table 5-1. 


The remote command terminal, used by the DCL command SET HOST, also makes use of the features listed 
in Section 5.2. 


Table 5-1 Supported Terminal Devices 
Interfaces Limes. «—=«(OUtPUt_— Split Speed = Bus rode Control 
Silo DMA 
CXY08 8 Yes! Yes Yes Q-bus Full 
CXA16 16 Yes! Yes Yes Q-bus No 
CXB16 16 Yes! Yes Yes Q-bus No 
DZQ11 4 No No Yes Q-bus No 
DZQ11-CR 4 No No Yes Q-bus No 
MicroVAX 2000 4 No No Yes None No 
MicroVAX 3100 4 No No Yes None No 
DZV11 4 No No No Q-bus No 
DHQ11 8 Yes Yes Yes Q-bus Full 
DHU11 16 Yes! Yes Yes UNIBUS Full 
DHV11 8 No Yes Yes Q-bus Full 
DMB32 8 No Yes Yes VAXBI bus Full 


169 


Terminal Driver 
Supported Terminal Devices 


Table 5-1 Supported Terminal Devices (Continued) 
Terminal No. of : International 
Interfaces Lines Output Split Speed oe Modem Control 
Silo DMA 
DHB32 16 No Yes Yes VAXBI bus Full 
DSH32 8 Yes No Yes MicroVAX No 
2000, 
MicroVAX 
3100 
DMF32 8 Yes Yes2 Yes UNIBUS Yes 
DMZ32 24 Yes Yes Yes UNIBUS Full 
DZ11 8/16 No No No UNIBUS No 
DZ32 8 No No Limited UNIBUS No 
LAT 3 No Yes 3 N/A 3 
VAX 8200 serial 4 No No No? None No 
lines 
VAXstation 3100 4 No No Yes None No 
VAXstation 4000 2 No No Yes None No 
DEC 2000 Model 2 No No No None Full 
300 
DEC 2000 4,8 Yes No No EISA Full 
Model 300° 
AlphaServer 2100 2 No No No None Full 
AlphaServer® 4,8 Yes No No EISA Full 
DEC 3000 Model 3 No Yes® No None Full 
300 
DEC 3000 Model 4 No Yes? No None Full 
400 
DEC 3000 Model 4 No Yes” No None Full 
500 
DEC 4000 Model 2 No No No None Full 
600 


1. Depends on whether the DHV or DHU mode is selected when the board is installed 
2. Lines 0 and 1. 
3. Server-dependent. 
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. The operating system always supports the first serial line as a console interface. The first serial 


line and the remaining three serial lines are also supported as user terminal interfaces at a 
maximum speed of 1200 baud in configurations that can include a LAT terminal interface, but do 
not include other terminal interfaces. 


. Optional multifunctional serial/parallel PC4XD-AA adapter card. You can daisy-chain up to four 


boards in one system, resulting in 14, 32, or 64 ports. 


. Communications only if not booted as an alternate console. 
. Communications only. 


5.2 Terminal Driver Features 


The terminal driver provides the following features: 


Input processing 


Command-line editing and command recall 

Control characters and special keys 

Input character validation (read verify) 

American National Standard Institute (ANSI) escape sequence detection 
Type-ahead feature 

Specifiable or default input terminators 


Special operating modes, such as NOECHO and PASTHRU 


Output processing 


Efficiency 
Limited full-duplex operation 


Formatted or unformatted output 


Dialup support 


Modem control 
Hangup on logout 


Preservation of process across hangups 


Miscellaneous 


Terminal/mailbox interaction 
Autobaud detection 


Out-of-band control character handling 
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5.2.1 Input Processing 


The terminal driver defines many terminal characteristics and read function modifiers, which provide a wide 
range of options to an application program. These options allow multiple levels of control over the terminal 
driver's input process, ranging from the default of command-line editing that provides a highly flexible user 
interface, to the PASTHRU mode, which inhibits input process interpretation of data. 


5.2.1.1 Command-Line Editing and Command Recall 


The terminal driver input process defines a bounded set of line editing functions. You can access these 
functions with control keys on all keyboards, and with some special keys on certain keyboards as well. You 
can move the cursor in single-character increments (left arrow or Ctrl/D, right arrow or Ctrl/F) or in 
multicharacter increments, to the beginning of the line (Ctrl/H) or end of the line (Ctrl/E). The terminal driver 
supports both insert character and overstrike character modes. The insert or overstrike mode is the 
terminal's default characteristic! at the beginning of a read operation, but you can change it with the toggle 
insert/overstrike key (Ctrl/A). You can delete characters in word increments (Ctrl/J or line feed) and 
beginning-of-the-line increments (Ctrl/U). 


When you use the terminal driver's editing functions, the following restrictions result: 


e You cannot move the cursor to a previous line after a line wrap. 


e You cannot insert a character if the insertion would force a line wrap or if a tab follows the current cursor 
position. 


e You cannot delete a word at the beginning of a line after a line wrap. 
e You cannot assign the line editing function to other keys. 


Command recall, initiated by Ctrl/B or the up arrow, returns the last line entered to the command-line buffer. 
At this point, you edit or reenter the line by pressing the Return key. DCL extends command recall to the last 
20 commands by using the TRM$M_TM_NORECALL modifier to disable the terminal driver's recall 
mechanism. 


Any control key that is not defined by line editing is ignored. For application programs that require control 
key input but do not perform QIO functions with special read modifiers, the SET TERMINAL/NOLINE_EDIT 
DCL command restores most of the terminal driver behavior described under OpenVMS Versions 3.0 through 
3.7. 


5.2.1.2 Control Characters and Special Keys 


A control character is a character that controls action at the terminal rather than passing data to a process. 
An ASCII control character has a code between 0 and 31, and 127 (hexadecimal 0 through 1F, and 7F); that is, 
all normal control characters plus DELETE. (Table C-1 lists the numeric values for all control characters.) 


You enter some control characters at the terminal by simultaneously pressing the Ctrl key and a character 
key, such as Ctrl/x. Table 5-2 lists the terminal control characters. You can change control character echo 
strings (Ctrl/C, Ctrl/Y, Ctrl/O, and Ctrl/Z) on a systemwide basis (refer to the HP OpenVMS System 
Management Utilities Reference Manual). You enter special keys, such as Return, Line Feed, and Escape, by 
pressing a single key. 


1. HP suggests that new users specify overstrike mode. 
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Several of the control characters do not function as described if the DCL command SET 
TERMINAL/LINE_EDIT is not specified. Refer to the HP OpenVMS DCL Dictionary for information on line 
editing function keys and the SET TERMINAL command. 


Table 5-2 Terminal Control Characters 


Control Character 


Meaning 


Cancel(Ctrl/C) 


Delete Character 
(DELETE) 


Delete line (Ctrl/U) 


Delete word (Ctrl/J or F13) 
(Line feed) 


Gains the attention of the enabling process if the user program has enabled a 
Ctrl/C AST. If a Ctrl/C AST is not enabled, Ctrl/C is converted to Ctrl/Y (see 
Section 5.4.3.2). 


The terminal performs a carriage-return/line-feed combination (carriage 
return followed by a line feed), echoes CANCEL, and performs another 
carriage-return/line-feed combination. If the terminal has the ReGIS 
characteristic or if Ctrl/Y is pressed, the cancel ReGIS escape sequence is 
sent. 


Additional consequences of Ctrl/C are as follows: 


e The type-ahead buffer is emptied. 
e Ctrl/S and Ctrl/O are reset. 


e All queued and in-progress write operations and all in-progress read 
operations are successfully completed. The status return is 
SS$_CONTROLGC, or SS$_CONTROLY if Ctrl/C is converted to Ctrl/Y. 


The F6 key maps to Ctrl/C on the following terminal types: LK201, LK46W, 
LK461, LK463, and other compatible LK-series keyboards. 


Note that Ctrl/C is generally translated to Ctrl/Y for processing within DCL, 
unless you have a Ctrl/C handler. Use LIBSENABLE_CTRL and 
LIB$DISABLE_CTRL to get Ctrl/C and Ctrl/Y handled within your 
application. Example 5-4 shows a programming example that demonstrates 
Ctrl/Y and Ctrl/C handling under OpenVMS. 


Removes the last character entered from the input stream. 


DELETE (decimal 127 or hexadecimal 7F) is ignored if there are currently 
no input characters. Hardcopy terminals echo the deleted character enclosed 
in backslashes. For example, if the character z is deleted, \z\is echoed (the 
second backslash is echoed after the next non-DELETE character is 
entered). Terminals that have the TT$M SCOPE characteristic echo 
DELETE by removing the character. 


Purges current input data. When Ctrl/U is entered before the end of a read 
operation, the current input line is deleted. (In the case of a line wrap, Ctrl/U 
deletes only a line at a time.) If line editing is enabled (SET 
TERMINAL/LINE_EDIT is specified), the data from the beginning of the 
line to the current cursor position is deleted. 


Deletes the word before the cursor. Word terminators are all control 
characters, space, comma, dash, period, and!'#$&'()+@[\1]1%* {| ~/ 
: ; = ? (see Appendix C). 
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Table 5-2 Terminal Control Characters (Continued) 


Control Character 


Meaning 


Discard output (Ctrl/O) 


End of line (Ctrl/E) 
Exit (Ctrl/Z or F10) 


Interrupt (Ctrl/Y) 


Move cursor left (Ctrl/D) 
Move cursor right (Ctrl/F) 


Move cursor to beginning of 
line (Ctrl/H or F12) 
(Backspace) 


Purge type-ahead (Ctrl/X) 


Recall (Ctrl/B or up arrow) 
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Discards output. Action is immediate. All output is discarded until the next 
read operation, the next write operation with a IO$M_CANCTRLO modifier, 
or the receipt of the next Ctrl/O. The terminal echoes OUTPUT OFF. The 
current write operation (if any) and write operations performed while Ctrl/O 
is in effect are completed with a status return of SS$_CONTROLO. 


A second Ctrl/O, which reenables output, echoes OUTPUT ON. CtrI/C, Ctrl/Y, 
and Ctrl/T cancel Ctrl/O. 


Moves the cursor to the end of the line. 


Echoes EXIT when Ctrl/Z is entered as a read terminator. By convention, 
Ctrl/Z constitutes end-of-file. 


Ctrl/Y is a special interrupt or attention character that is used to invoke the 
command interpreter for a logged-in process. Ctrl/Y can be enabled with an 
IO$M_CTRLYAST function modifier to a IO$_SETCHAR or IO$_SETMODE 
function code. The command interpreter's Ctrl/Y AST handler always takes 
precedence over a user program's Ctrl/Y AST handler 


Entering Ctrl/Y results in an AST to an enabled process to signify that the 
user entered Ctrl/Y from the terminal. The terminal performs a 
carriage-return/line-feed combination, echoes INTERRUPT, and performs 
another carriage-return/line-feed combination if the AST and echo are 
enabled. Ctrl/Y is ignored (and not echoed) if the process is not enabled for 
the AST. 


Additional consequences of Ctrl/Y are as follows: 


e The type-ahead buffer is flushed. 
e Ctrl/S and Ctrl/O are reset. 


e All queued and in-progress write operations and all in-progress read 
operations are successfully completed with a 0 transfer count. The status 
return is SS$_ CONTROLY. 


e The cancel ReGIS escape sequence is sent. 
Moves the cursor one position to the left. 
Moves the cursor one position to the right. 


Moves the cursor to the beginning of the line. 


Purges the type-ahead buffer and performs a Ctrl/U operation. Action is 
immediate. If a read operation is in progress, the operation is equivalent to 
Ctrl/U. 


Recalls the last command entered. DCL extends recall to several commands. 
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Table 5-2 Terminal Control Characters (Continued) 


Control Character 


Meaning 


Redisplay input (Ctrl/R) 


Restart output (Ctrl/Q) 


RET (Return) 


Stop output (Ctrl/S) 


TAB(Ctrl/I) 


Status (Ctrl/T) 


Toggle insert/overstrike 
(Ctrl/A or F14) 


Redisplays current input. When Ctrl/R is entered during a read operation, a 
carriage-return/line-feed combination is echoed on the terminal, and the 
current contents of the input buffer are displayed. If the current operation is 
a read with prompt (I0$_READPROMPT) operation, the current prompt 
string is also displayed. Ctrl/R has no effect if the characteristic 
TT$M_NOECHO is set. 


Controls data flow; used by terminals and the driver. Restarts data flow to 
and from a terminal if previously stopped by Ctrl/S. The action occurs 
immediately with no echo. Ctrl/Q is also used to solicit read operations. 


Ctrl/Q is meaningless if the line does not have the characteristic 
TT$M_TTSYNC, the characteristic TT$M_READSYNC, or is not currently 
stopped by CtrlI/S. 


If used during a read (input) operation, RET echoes a 
carriage-return/line-feed combination. All carriage returns are filled on 
terminals with TT$M_CRFILL specified. 


Controls data flow; used by both terminals and the terminal driver. Ctrl/S 
stops all data flow; the action occurs immediately with no echo. Ctrl/S is also 
used to stop read operations. Ctrl/S is meaningful only if the terminal has 
either the TT$M_TTSYNC characteristic or the TT$M READSYNC 
characteristic. 


Tabs horizontally. Advances to the next tab stop on terminals with the 
characteristic TT$M_MECHTAB, but the terminal driver assumes tab stops 
on MODULO 8 (multiples of 8) cursor positions. On terminals without this 
characteristic, enough spaces are output to move the cursor to the next 
MODULO 8 position. 


Displays the current time. Ctrl/T also displays the current node and user 
name, the name of the image that is running, and information about system 
resources that have been used during the current terminal session. 


Changes current edit mode from insert to overstrike, or from overstrike to 
insert. The default mode (as set with SET TERMINAL/LINE_EDIT) is reset 
at the beginning of each line. 


5.2.1.3 Read Verify 


The read verify instructions provided by the terminal driver allow validation of data as each character is 
entered. Invalid characters are not echoed and terminate the operation. The terminal driver does not support 
full function field processing. Large data entry applications should use one of the DECforms, FMS, or TDMS 
layered products, which support the entire data entry environment. 
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5.2.1.4 Escape and Control Sequences 


Escape and control sequences provide additional terminal control not furnished by the control characters and 
special keys (see Section 5.2.1.2). Escape sequences are strings of two or more characters, beginning with the 
escape character (decimal 27 or hexadecimal 1B), which indicate that control information follows. Many 
terminals send and respond to such escape sequences to request special character sets or to indicate the 
position of a cursor. 


The set mode characteristic TT$M_ESCAPE (see Table 5-5) is used to specify that terminal lines can generate 
valid escape sequences. Also, the read function modifier IO$M_ESCAPE allows any read operation to 
terminate on an escape sequence regardless of whether TT$M_ESCAPE is set. If either TT$M_ESCAPE or 
IO$M_ESCAPE is set, the terminal driver verifies the syntax of the escape sequences. The sequence is always 
considered a read function terminator and is returned in the read buffer; a read buffer can contain other 
characters that are not part of an escape sequence, but a complete escape sequence always terminates a read 
operation. The return information in the read buffer and the I/O status block includes the position and size of 
the terminating escape sequence in the data record (see Section 5.4.1.4). 


Any escape sequence received from a terminal is checked for correct syntax. If the syntax is not correct, 
SS$_BADESCAPE is returned as the status of the I/O. If the escape sequence does not fit in the user buffer, 
SS$_PARTESCAPE is returned. If SS$_PARTESCAPE is returned, the application program must issue 
enough single-character read requests, without timeout, to read the remaining characters in the escape 
sequence, while parsing the syntax of the rest of the escape sequence. Use of the TRM$_ESCTRMOVR item 
code prevents SS$_PARTESCAPE errors. No syntax integrity is guaranteed across read operations. Escape 
sequences are never echoed. Valid escape sequences take any of the following forms (hexadecimal notation): 


ESC <int>...<int><fin> (7-bit environment) 


CSI <int>...<int><fin> (8-bit environment) 


The keywords in the escape sequences indicate the following: 


ESC The ESC key, a byte (character) of 1B. This character introduces the escape sequence in a 7-bit 
environment. 
CSI The control sequence introducer, a byte (character) of 9B. This character introduces the escape 


sequence in a 8-bit environment. 


<int> An “intermediate character” in the range of 20 to 2F. This range includes the space character 
and 15 punctuation marks. An escape sequence can contain any number of intermediate 
characters, or none. 


<fin> A “final character” in the range of 30 to 7E. This range includes uppercase and lowercase 
letters, numbers, and 13 punctuation marks. 


Three additional escape sequence forms are as follows: 


ESC <;> <20-2F>...<30-7E> 
ESC <20-2F>...<30-7E> 
ESC <O><20-2F>...<40-7E> 


Control sequences, as defined by the ANSI standard, are escape sequences that include control parameters. 
Control sequences have the following format: 


ESC [ <par>...<par><int>...<int><fin> (7-bit environment) 


CSI <par>...<par><int>...<int><fin> (8-bit environment) 
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The keywords in the control sequences indicate the following: 


ESC The ESC key, a byte (character) of 1B. 

[ A control sequence, a byte (character) of 5B. 

CSI The control sequence introducer, a byte (character) of 9B. 
<par> A parameter specifier in the range of 30 to 3F. 

<int> An “intermediate character” in the range of 20 to 2F. 
<fin> A “final character” in the range of 40 to 7E. 


For example, the position cursor control sequence is ESC [ Pl ; Pc H where PI is the desired line position and 
Pc is the desired column position. 


The user guides for the various terminals list valid escape and control sequences. For example, the VT100 
User Guide lists the escape and control sequences for VT100 terminals. 


Section 5.2.1.2 describes control character functions during escape sequences. 


Table C-2 lists the valid ANSI and DIGITAL private escape sequences for terminals that have the 
TT2$M_ANSICRT, TT2$M_DECCRT, TT2$M_DECCRT2, TT2$M_AVO, TT2$M_EDIT, and TT2$M_BLOCK 
characteristics (see Table 5-6). Table C-2 also lists assumed and selectable ANSI modes and selectable 
DIGITAL private modes. Only the names of the escape sequences and modes are listed (for more information, 
refer to the specific user guide for the various terminals). Unless otherwise noted, the operation of escape 
sequences and modes is identical to the particular terminals that implement these features. 


5.2.1.5 Type-Ahead Feature 


Input (data received) from a terminal is always independent of concurrent output (data sent) to a terminal. 
This feature is called type-ahead. Type-ahead is allowed on all terminals, unless explicitly disabled by the set 
mode characteristic, inhibit type-ahead (TT$M_NOTYPEAHD; see Table 5-5 and Section 5.4.3). 


Data entered at the terminal is retained in the type-ahead buffer until the user program issues an I/O request 
for a read operation. At that time, the data is transferred to the program buffer and echoed at the terminal 
where it was typed. 


Deferring the echo until the read operation is active allows the user process to specify function code modifiers 
that modify the read operation. These modifiers can include, for example, noecho (IO$M_NOECHO) and 
convert lowercase characters to uppercase (IO$M_CVTLOW) (see Table 5-7). 


If a read operation is already in progress when the data is typed at the terminal, the data transfer and echo 
are immediate. 


The action of the driver when the type-ahead buffer fills depends on the set mode characteristic 
TT$M_HOSTSYNC (see Table 5-5 and Section 5.4.3). If TT$M_HOSTSYNC is not set, Ctrl/G (bell) is 
returned to inform you that the type-ahead buffer is full. The buffer must then be emptied, at which time a 
status of SS$¢_ DATAOVERUN is returned. If TT$M_HOSTSYNC is set, the driver stops input by sending a 
Ctrl/S and the terminal responds by sending no more characters. These warning operations begin eight 
characters before the type-ahead buffer fills unless the TT2$M_ALTYPEAHD characteristic is set. In that 
case, the system generation parameter TTY_ALTALARM is used. The driver sends a Ctrl/Q to restart 
transmission when the type-ahead buffer empties completely, and the user has posted another READ QIO. 


The type-ahead buffer length is variable, with possible values in the range of 0 through 32,767. The length 
can be set on a systemwide basis through use of the system generation parameter TTY_TYPAHDSZ. 
Terminal lines that do a large amount of bulk input should use the characteristic TT2$M_ALTYPEAHD, 
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which allows the use of a larger type-ahead buffer specified by the system generation parameters 
TTY_ALTYPAHD and TTY_ALTALARM. (TTY_ALTYPAHD specifies the total size of the alternate 
type-ahead buffer; TTY_ALTALARM specifies the threshold at which a CtrI/S is sent.) 


Certain input-intensive applications, such as block mode input terminals, can take advantage of an 
optimization in the driver. If a terminal has the characteristic TT2$M_PASTHRU and the read function 
IO$M_NOECHO is specified, data is placed directly into the read buffer and thereby eliminates the overhead 
for moving the data from the type-ahead buffer. 


5.2.1.6 Line Terminators 


A line terminator is the control sequence that you type at the terminal to indicate the end of an input line. 
Optionally, the application can specify a particular line terminator or class of terminators for read operations. 


Terminators are specified by an argument to the QIO request for a read operation. By default, they can be any 
ASCII control character except FF, VT, LF, TAB, or BS (see Appendix C). If line editing is enabled, the only 
terminators are CR, Ctrl/Z, or an escape sequence. Control keys that do not have an editing function are 
nonfunctioning keys. If included in the request, the argument is a user-selected group of characters (see 
Section 5.4.1.2). 


All characters are 7-bit ASCII characters unless data is input on an 8-bit terminal (see Section 5.4.1). The 
characteristic TT$M_EIGHTBIT determines whether a terminal uses the 7-bit or 8-bit character set; see 
Table 5-5. All input characters (except some special keys; see Section 5.2.1.2) are tested against the selected 
terminators. The input is terminated when a match occurs or your input buffer fills. 


The terminal driver notifies the job controller to initiate login when it detects a carriage-return terminator on 
a line with no current process (provided the line is not a secure server or the type-ahead feature has not been 
disabled). A bell character is sent when the notification occurs. A notification character other than the bell 
character may be specified by setting the system generation parameter TTY_AUTOCHAR. 


5.2.1.7 Special Operating Modes 


The terminal driver supports many special operating modes for terminal lines. (Table 5-5 and Table 5-6 list 
these modes.) All special modes are enabled or disabled by the set mode and set characteristics functions (see 
Section 5.4.3). 


5.2.2 Output Processing 


Output handling is designed to be very efficient in the terminal driver. For example, on multiplexers that 
support both silo and direct memory access (DMA) ouput, the driver considers record size to decide 
dynamically which mode will result in the least overhead. The block size specified by the system generation 
parameter TTY_DMASIZE is the minimum size block that can be used in a DMA operation. 


5.2.2.1 Duplex Modes 


The terminal driver can execute in either half- or full-duplex mode. These modes describe the terminal driver 
software, specifically the ordering algorithms used to service read and write requests, not the terminal 
communication lines. 


In half-duplex mode, all read and write requests are inserted onto one queue. The terminal driver removes 
requests from the head of this queue and executes them one at a time; all requests are executed sequentially 
in the order in which they were issued. 
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In full-duplex mode, read requests (and all other requests except write requests) are inserted onto one queue 
and write requests onto another. The existence of two queues allows the driver to recognize the presence of 
two requests, such as a read request and a write request at the same time. However, the driver does not 
execute the read request and the write request simultaneously. When it is ready to service a request, the 
driver decides which request—the read request or the write request—to process next. 


The following terms describe the state of a read request: 


e A read request is active when the terminal driver removes that request from the head of the I/O queue. 
e Aread request is started when the terminal driver moves the first character into the read buffer. 


In the terminal driver, write requests usually have priority. A write request can interrupt an active, but not 
started, read request. 


The terminal driver does not start a read request until all outstanding writes are completed. This means that 
a read request could be removed from the head of the read queue while write requests are outstanding, but 
the first character is not moved into the read buffer until all outstanding writes are completed. 


Once a read request is started, all write requests are queued until the read completes. However, during a read 
operation many write requests can be executed before the first input character is entered at the terminal. 
Terminal lines that have the TT$M_NOECHO characteristic, or read functions that include the 
IO$M_NOECHO function modifier, do not inhibit write operations in full-duplex mode. 


If a write function specifies the IO$M_BREAKTHRU modifier, the write operation is not blocked, even by an 
active read operation. IO$M_BREAKTHRU does not change the order in which write operations are queued. 


When all I/O requests are entered using the Queue I/O Request and Wait ($QIOW) system service, there can 
be only one current I/O request at a time. In this case, the order in which requests are serviced is the same for 
both half: and full-duplex modes. 


The type-ahead buffer always buffers input data for which there is no current read request, in both half- and 
full-duplex modes. 


5.2.2.2 Formatting of Output 


By default, output data is subject to formatting by the terminal driver. This formatting includes actions such 
as wrapping, tab expansion, uppercase, and fallback conversions. Applications that do not require formatting 
of data can write with the IO$M_NOFORMAT modifier and thereby reduce overhead. IO$M_NOFORMAT 
overrides all formatting except fallback translation. Setting the PASTHRU mode (TT2$M_PASTHRU) is 
equivalent to writing with the noformat modifier. 


Fallback conversions occur regardless of formatting mode. 


5.2.2.3 SET HOST Facility and Output Buffering 


The SET HOST facility emulates the terminal driver in the way it writes data to the terminal by stopping the 
display as soon as the abort character is entered. However, the SET HOST facility behaves differently from 
the terminal driver in that it buffers output data from the program that is executing. Occasionally, this causes 
a perception problem for the user when the program is aborted with a Ctrl/C, Ctrl/Y, or an out-of-band abort 
character. The user expects the program to terminate and the display to stop immediately. 


CTDRIVER and RTPAD 


When used between two systems, the SET HOST facility consists of two components: RTPAD on the local 
node and CTDRIVER on the remote node. Both components buffer output data to enhance performance when 
using wide area networks. CTDRIVER performs the initial buffering, queues the buffers for network transfer, 
and returns a successful write status. The user should note that the local terminal display reflects the output 
of the executing program after the data has been buffered and transferred over the network—not as the 
output buffers are filled on the remote node. 
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The delay between execution of an application and the display of its output can lead to several anomalies in 
the effects of Ctrl/C, Ctrl/Y, and out-of-band abort characters. 


Output Line Not in Sequence Following an Abort Character 


After you enter an abort character (Ctrl/C, Ctrl/Y, or an out-of-band abort character) that causes the input or 
output to be aborted, it is possible to receive an additional line of output. This occurs when the application 
program calls $QIO (either directly or indirectly through RMS or language support routines) to output data to 
a buffer at the same time the abort character is entered. 


When CTDRIVER receives the abort character (Ctrl/C, Ctrl/Y, or an out-of-band abort character) from the 
network, it flushes the current output buffers and aborts any pending read operations. However, if the 
application program calls $QIO with a write operation when the abort character is entered, the $QIO write 
data is still buffered and then displayed. The data may not be the next output in sequence from the user's 
point of view, since all the previous output buffers in CTDRIVER were flushed and the data in them was not 
displayed. 


When using the terminal driver, the effect of an abort character on the display screen is different. The 
terminal driver does not buffer output from the application during program execution. If the application 
program has just called $QIO with a write operation when the abort character is entered, then the $QIO 
write data is displayed. Because all write operations are sequential and do not complete until the output is 
actually displayed, the additional line displayed is in sequence. There is no break in the data. Normally, the 
user will not notice that there is an additional line. 


Extra Input Prompt Following an Abort Character 


For connections between systems, the CTERM protocol allows CTDRIVER to synchronize with RTPAD before 
displaying any more data on the terminal. 


NOTE Prior to VAX VMS Version 5.2, a control character entered during program execution to abort 
input and output could cause the system to display more than one input prompt. 


If the SET HOST facility is used between systems running VMS Version 5.2 and an earlier 
version, the extra input prompt is still displayed. 


Processing Abort Characters 


The abort character AST is delivered after the message describing the aborted read operation has been 
received. Therefore, the read status should be set very shortly after the abort character AST is delivered to 
the application. Note, however, these are still two asynchronous events, and the application must still 
synchronize with the completing read operation. 


NOTE Prior to VAX VMS Version 5.2, if an application had a read operation pending and had queued 
a Ctrl/C, Ctrl/Y, or out-of-band abort character AST, it was possible to queue multiple read 
operations unknowingly when the read operation was aborted. 


Captive Command Procedures and Ctrl/Y 


CTDRIVER and RTPAD emulate the terminal driver in that the current read operation and all pending write 
operations abort when Ctrl/Y is entered. However, the pending write operations also include all the buffered 
output that occurred and that would have been output before the Ctrl/Y was entered but due to the buffering 
was not. 
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The effect of the buffering can be confusing if a Ctrl/Y is entered when a captive command procedure is 
executing. During execution of captive command procedures, DCL has a Ctrl/Y pending. When this AST is 
delivered, DCL only reenables it; no other action is performed. In that case, if the program being executed 
only performs output, it appears that the program was aborted by the Ctrl/Y. Actually, the program completed 
execution before the Ctrl/Y was entered, and the Ctrl/Y merely discarded all the buffered output. 


5.2.3 Dialup Support 


The operating system supports modem control (for example, Bell 103A, Bell 113, or equivalent) for all 
supported multiplexers in autoanswer, full-duplex mode. The terminal driver does not support half-duplex 
operations on modems such as the Bell 202. Also not supported are modems that use circuit 108/1 (connect 
data set to line signal) in place of the data terminal ready (DTR) signal. Most U.S. and European modems use 
the data terminal ready signal, which is the signal supported by the operating system. 


5.2.3.1 Modem Signal Control 


Dialup lines with the characteristic TT$M_MODEM are monitored periodically to detect a change in the 
modem carrier signals data set ready (DSR), calling indicator (RING), or request to send (RTS). The system 
generation parameter TTY_SCANDELTA establishes the dialup monitoring period for multiplexers that do 
not support modem signal transition interrupts (see Table 5-1). 


If a line's carrier signal is lost, the driver waits 2 seconds for the carrier signal to return. If bit 0 of the system 
generation parameter TTY_DIALTYPE is set to 1, the driver does not wait. Bit 0 is 0 by default for countries 
with Bell System standards, but that bit should be set to 1 for countries with International Telegraph and 
Telephone Consultative Committee (CCITT) standards. If the carrier signal is not detected during this time, 
the line is hung up. The hangup action can signal the owner of the line, through a mailbox message, that the 
line is no longer in use. (No dial-in message is sent; the unsolicited character message is sufficient when the 
first available data is received.) The line is not available for a minimum of 2 seconds after the hangup 
sequence begins. The hangup sequence is not reversible. If the line hangs up, all enabled Ctrl/Y and 
out-of-band ASTs are delivered; the Ctrl/Y AST P2 argument is overwritten with SS$_HANGUP. The I/O 
operation in progress is canceled, and the status value SS$_HANGUP is returned in the I/O status block. 
DCLis responsible for process deletion after Ctrl/Y is delivered. If the process is suspended, DCL cannot run, 
and therefore deletion cannot occur, until the process is resumed. 


NOTE Some systems, such as the VAXstation 3100, provide built-in serial lines using 6-pin modular 
jacks. These lines do not provide the minimum required modem signals. Although the 
hardware may allow a dial-out connection to be established, hangup cannot be detected and 
process deletion will not occur on these lines. 


For terminals with the TT$M_MODEM characteristic, TT$M_REMOTE reflects the state of the carrier 
signal. TT$M_REMOTE is set when the carrier signal changes from off to on, and cleared when the carrier 
signal is lost. 


A line that does not have TT$M_MODEM set does not respond to modem signals or set the DTR signal. 
Modem signals can be set and sensed manually through use of the IO$M_MAINT function modifier (see 
Section 5.4.3.3). 


The terminal driver default modem protocol meets the requirements of the United States and of European 
countries. This protocol is capable of working in automatic answer mode and can also perform manually 
dialed outgoing calls. The protocol supports the requirements of most known international telephone 
networks. Enhanced modem features are used on multiplexers that support them; processor polling is not 
necessary. The protocol also functions in a subset mode for the multiplexers that do not support full modem 
signals (see Table 5-1). 


181 


Terminal Driver 
Terminal Driver Features 


Table 5-3 lists the control and data signals used in a full modem control mode configuration (in a two-way 
simultaneous, symmetrical transmit mode). Figure 5-1 is a flowchart that shows a typical signal sequence for 
a terminal operation in this mode. The flowchart shows the states that the modem transition code goes 
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through to detect different types of transitions in modem state. These transitions allow the driver to detect 
loss of lines that have been idle for several minutes. Modem states do not affect the ability of the system to 
transmit characters. 


Figure 5-1 Modem Control: Two-Way Simultaneous Operation 
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Set mode function modifiers are provided to allow a process to activate or deactivate modem control signals 
(see Section 5.4.3.3). 


Bit 1 of the system generation parameter TTY_DIALTYPE enables alternate modem protocol on a 
systemwide basis. If bit 1 is 0 (the default), the RING signal is not used. If bit 1 is 1, the modem protocol 
delays setting the DTR signal until the RING signal is detected. 


Remote terminal connections have a timeout feature for the security of dialup lines. If no channel is assigned 
to the port within 30 seconds, or a port with an assigned channel is not allocated, the DTR signal is dropped. 
Such action prevents an unused terminal from tying up a line. However, there are configurations (such as a 
printer connected to a remote line) in which the line should not be dropped even though it is not being used 
interactively. To bypass the 30-second timeout, set the system generation parameter TTY_DIALTYPE to 4. 
(Note that if TTY_DIALTYPE is equal to 4, all dialup lines will skip the timeout waiting for a channel to be 
assigned.) 


Table 5-3 Control and Data Signals 


Signal Source MUX! Meaning 


Transmitted data Computer All The data originated by the computer and 
(TxD) transmitted through the modem to one or more 
remote terminals. 


Received data (RxD) Modem All The data generated by the modem in response to 
telephone line signals received from a remote 
terminal and transferred to the computer. 


Request to send Computer Full If present (ON condition), RTS directs the modem 

(RTS) to assume the transmit mode. If not present(OFF 
condition), RTS directs the modem to assume the 
nontransmit mode after all transmit data has 
been transmitted. 


Clear to send (CTS) Modem Full Indicates whether the modem is ready (ON 
condition) or not ready (OFF condition) to 
transmit data on the telephone line. 


Data set ready (DSR) Modem Full If present (ON condition), DSR indicates that the 
modem is ready to transmit and receive; that is, 
the modem is connected to the line and is ready to 
exchange further control signals with the 
computer to initiate the exchange of data. 


If DSR is not present (OFF condition), the modem 
is not ready to transmit and receive. If DSR is 
detected, the operating system initiates a 
30-second timer. This ensures that the phone line 
will be disconnected if CARRIER is not detected. 


Data channel Modem All If present (ON condition), CARRIER indicates 

received line signal that the received data channel line signal is 

detector (CARRIER) within appropriate limits, as specified by the 
modem. If not present (OFF condition), the 
received signal is not within appropriate limits. 


184 


Terminal Driver 
Terminal Driver Features 


Table 5-3 Control and Data Signals (Continued) 
Signal Source MUX! Meaning 
Data terminal ready Computer All If present (ON condition), DTR indicates that the 
(DTR) computer is ready to operate, prepares the modem 


to connect to the telephone line, and maintains 
the connection after it has been made by other 
means. DTR can be present whenever the 
computer is ready to transmit or receive data. If 
DTR is not present (OFF condition), the modem 
disconnects the modem from the line. 


Calling indicator Modem All Indicates whether a calling signal is being 

(RING) received by the modem. Bit 1 of the system 
generation parameter TTY_DIALTYPE must be 
set (=1). If RING is detected, the operating system 
initiates a 30-second timer. This ensures that the 
phone line will be disconnected if CARRIER is not 
detected. 


1. Multiplexers (All = any supported controller; Full = DZ32, DMF32, DMB32, DMZ32, DHU11, 
DHV11, and CXY08). 
5.2.3.2 Hangup on Logging Out 


By default, logging out on a line with modem signals will not break the connection. If TT2$M_HANGUP is 
set, modem signals are dropped when the process logs out. If TT2$M_MODHANGUP is set, no privilege is 
required to change the state of TT2$M_HANGUP. By setting TT2M_HANGUP, system managers can prevent 
nonprivileged users who are not logged in from tying up a dial-in line. 

5.2.3.3 Preservation of a Process Across Hangups 

Disconnectable terminals allow a connection to a physical terminal line to be broken without losing the job. 


On VAX systems, the following SYSGEN command allows terminals to be disconnectable terminals: 


SYSGEN> CONNECT VTAO/NOADAPTER/DRIVER=TIDRIVER 


On Alpha and 164 systems, the following SYSMAN command allows terminals to be disconnectable terminals: 


SYSMAN> IO CONNECT VTAO/NOADAPTER/DRIVER=SYSSTIDRIVER 


After this command is entered, a terminal with the TT2$M_DISCONNECT characteristic logs in as VTAn:, 
rather than with the physical terminal name. When a terminal is set up in this manner, no input or output 
operations are allowed to the physical device; I/O is automatically redirected to the appropriate virtual 
terminal. 


Following are four ways in which a terminal can become disconnected: 

e Modem signals between the host and the terminal are lost. 

e Auser presses the BREAK key on a terminal that has the TT2$M_SECURE characteristic. 
e Auser enters the DCL command DISCONNECT. 

e Auser enters the DCL command CONNECT/CONTINUE. 
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After validated as a user, you can connect to a disconnected process in either of the following ways: 


e Allow the login process to make the connection. 


e Enter the DCL command CONNECT. 


5.2.4 Terminal/Mailbox Interaction 


Mailboxes are virtual I/O devices used to communicate between processes. The terminal I/O driver can use a 
mailbox to communicate with a user process. Chapter 4 describes the mailbox driver. 


A user program can use the Assign I/O Channel ($ASSIGN) system service to associate a mailbox with one or 
more terminals. The terminal driver sends messages to this mailbox when terminal-related events that 
require the attention of the user image occur. 


Mailboxes used in this way carry status messages, not terminal data, from the driver to the user program. For 
example, when data is received from a terminal for which no read request is outstanding (unsolicited data), a 
message is sent to the associated mailbox to indicate data availability. On receiving this message, the user 
program reads the channel assigned to the terminal to obtain the data. Messages are sent to mailboxes under 
the following conditions: 


e Unsolicited data in the type-ahead buffer. The use of the associated mailbox can be enabled and disabled 
as a subfunction of the read and write requests (see Sections Section 5.4.1 and Section 5.4.2). (Initially, 
mailbox messages are enabled on all terminals. This is the default state.) Therefore, the user process can 
enter into a dialogue with the terminal after an unsolicited data message arrives. Then, after the dialogue 
is over, the user process can reenable the unsolicited data message function on the last I/O exchange. Only 
one message is sent between read operations. 


e Terminal hangup. When a remote line loses the carrier signal, it hangs up; a message is sent to the 
mailbox. When hangup occurs on lines that have the characteristic TT$M_REMOTE set, the line returns 
to local mode. 


¢ Broadcast messages. If the characteristic TT2$M_BRDCSTMBkX is set, broadcasts sent to a terminal are 
placed in the mailbox (this is independent of the state of TT$M_NOBRDCST). 


Messages placed in the mailbox have the following content and format (see Figure 5-2): 


¢ Message type. The codes MSG$_TRMUNSOLIC (unsolicited data), MSG$_TRMHANGUP (hangup), and 
MSG$_TRMBRDCST (terminal broadcast) identify the type of message. Message types are identified by 
the $MSGDEF macro. 


e Device unit number to identify the terminal that sent the message. 
e Counted string to specify the device name. 


e Controller name. 
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e Message (for broadcasts). 


Figure 5-2 Terminal Mailbox Message Format 
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Interaction with a mailbox associated with a terminal occurs through standard QIO functions and ASTs. 
Therefore, the process need not have outstanding read requests to an interactive terminal to respond to the 
arrival of unsolicited data. The process need only respond when the mailbox signals the availability of 
unsolicited data. Chapter 4 contains an example of mailbox programming. 


The ratio of terminals to mailboxes is not always one to one. One user process can have many terminals 
associated with a single mailbox. 


5.2.5 Autobaud Detection 


If you specify the /AUTOBAUD qualifier with the SET TERMINAL command, automatic baud rate detection 
is enabled, allowing the terminal baud rate to be set when you log in. The baud rate is set at login by pressing 
the Return key two or more times separated by an interval of at least one second. (Pressing a key other than 
Return might detect the wrong baud rate; if this occurs, wait for the login procedure to time out before 
continuing.) The supported baud rates are 110, 150, 300, 600, 1200, 1800, 2400, 3600, 4800, 9600, and 19,200. 
Newer Alpha systems can autobaud up to 57600. Parity is allowed on these lines. 


The autobaud function works with either even parity or no parity, but not with odd parity. If a line is set to 
even parity and has 7 bits of data, the line automatically switches to no parity if a terminal not generating 
parity attempts to log in. 


The SET TERMINAL qualifier /EIGHT_BIT specifies that the terminal uses 8-bit ASCII code. 
/NOEIGHT_BIT, which is the default, specifies 7-bit ASCII code. (If parity is specified, the parity bit is 
separate from the data bits.) The optimal settings for automatic baud rate detection on HP terminals are 
/NOEIGHT_BIT/PARITY=EVEN or /EIGHT_BIT/NOPARITY, although automatic baud rate detection also 
works with other combinations, such as /NOEIGHT_BIT/NOPARITY. 


Table 5-6 describes the terminal characteristic TT2$M AUTOBAUD, which allows the baud rate to be set 
automatically at login. 


HP does not usually recommend specifying the /FRAME qualifier with the SET TERMINAL command. The 
terminal driver selects the frame size (the number of data bits that the device can transmit) based on how the 
/PARITY and /EIGHT_BIT qualifiers are set. It might be necessary to change these values if the terminal is 
not made by HP. 
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5.2.6 Out-of-Band Control Character Handling 


All control characters (0 through 1F hexadecimal) can be enabled as out-of-band characters. Typing one of 
these characters immediately delivers an AST to the requesting process. DCL uses this mechanism to sense 
whether Ctrl/T has been entered. Out-of-band character options allow using the IO$M_INCLUDE function 
modifier to include the character in the data stream and the IO$M_ TT ABORT function modifier to abort the 
current input or output operation. 


5.3 Terminal Driver Device Information 


You can obtain information on terminal characteristics by using the Get Device/Volume Information 
($GETDVD system service. (Refer to the HP OpenVMS System Services Reference Manual.) The sense mode 
function provides an alternative means to obtain terminal characteristics; see Section 5.4.5. 


$GETDVI returns terminal characteristics when you specify the item codes DVI$_DEVCHAR, 
DVI$_DEVDEPEND, and DVI$_DEVDEPEND2. Table 5-4, Table 5-5, and Table 5-6 list these characteristics. 
Terminal characteristics are normally set during system generation to any one of, or a combination of, the 
values listed in Table 5-5. DVI$_DEVDEPEND returns a longword field in which the three low-order bytes 
contain the device-dependent characteristics and the high-order byte contains the page length. Page length 
can have a value in the range of 0 through 255. The $DEVDEF macro defines the device-independent 
characteristics, the $TTDEF macro defines the device-dependent characteristics, and the $TT2DEF macro 
defines the extended device-dependent characteristics. 


DVI$_DEVCLASS and DVI$_DEVTYPE return the device class and device type names, which are defined by 
the $DCDEF and $TTDEF macros, respectively. The device class for terminals is DC$_TERM. The terminal 
model determines the device type. For example, the device type for the VT240 is TT$_VT200_SERIES. 
DVI$_DEVBUFSIZ returns the page width, which can be a value in the range of 1 through 511. The driver 
does not accept a value of 0. 


Table 5-4 Terminal Device-Independent Characteristics 
Characteristic Meaning 

DEV$M_AVL Terminal is on line and available. 
DEV$M_CCL Carriage control is enabled. 
DEV$M_DET Terminal is detached. 
DEV$M_IDV Terminal is capable of input. 
DEV$M_ODV Terminal is capable of output. 
DEV$M_OPR Terminal is enabled as an operator console. 
DEV$M_REC Device is record-oriented. 
DEV$M_RTT Terminal has remote terminal UCB extension. 
DEV$M_SPL Device is spooled. 
DEV$M_TRM Device is a terminal. 
DEV$M_NET Terminal line is allocated for DECnet use. 
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Table 5-5 Terminal Characteristics 


Value! 


Meaning 


TT$M_CRFILL 


TT$M_EIGHTBIT 


TT$M_ESCAPE 


TT$M_HALFDUP 


TT$M_HOSTSYNC 


TT$M_LFFILL 


TT$M_LOWER 


TT$M_MBXDSABL 


TT$M_MECHFORM 


TT$M_MECHTAB 


TT$M_MODEM 


Terminal requires fill after the Return key is pressed (the fill type can be 
specified by the set mode function P4 argument). 


Terminal uses the 8-bit ASCII character set (see Appendix C). Terminals 
without this characteristic use the 7-bit ASCII code. In this case, the 

eighth bit is masked out on received characters and is ignored on output 
characters. The eighth bit is meaningful only if TT$M_EIGHTBIT is set. 


Terminal generates escape sequences (see Section 5.2.1.4). Escape 
sequences are validated for syntax. 


Terminal is in half-duplex mode (see Section 5.2.2.1). All read and write 
requests are executed sequentially. 


The host system is synchronized to the terminal. Ctrl/Q and Ctrl/S are 
used to control data flow and thus keep the type-ahead buffer from 
filling. TT$M_HOSTSYNC should always be set on LAT terminals. 


Terminal requires fill after the line-feed character is processed. (The fill 
can be specified by the set mode P4 argument.) 


Terminal has the lowercase character set. Unless the terminal is in the 
PASTHRU mode or IO$¢M_NOFORMAT is specified, all input and 
echoed lowercase characters (hexadecimal 61 to 7A) are converted to 
uppercase if TT$M_LOWER is not set. (The character ALTMODE 
(decimal 125 and 126, or hexadecimal 7D and 7E) converts to ESCAPE 
on terminals that do not have the lowercase characteristic 
TT$M_LOWER set.) 


Mailboxes associated with the terminal do not receive notification of 
unsolicited input or hangup (see Section 5.2.3). This bit can be set by 
tshe IO$M_DSABLMBxX function modifier for read requests and cleared 
by the IO$M_ENABLMBxX function modifier for write requests. 


Terminal has mechanical form feed. The terminal driver passes form 
feeds directly to the terminal instead of expanding to line feeds. 


Terminal has mechanical tabs and is capable of tab expansion. To 
accomplish correct line wrapping, the terminal driver assumes there are 
eight spaces between tab stops. 


Terminal line is connected to a modem. If TT$M_MODEM is set, the 
terminal driver automatically handles modem control. If 
TT$M_MODEM is not set, all modem signals are ignored. If 
TT$M_MODEM is set and then cleared, a hangup is declared on the 
terminal line if that line is in the remote state (TT$M REMOTE is set). 
If DTR and RTS are set with 
10$_SETMODE!IO$M_SET_MODEM!IO$M_MAINT on a nonmodem 
port, DTR and RTS goes off and then back on when the port is set for 
modem. 


TT$M_MODEM is not supported for LAT devices. 
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Table 5-5 Terminal Characteristics (Continued) 


Value! 


Meaning 


TT$M_NOBRDCST 
TT$M_NOECHO 


TT$M_NOTYPEAHD 


TT$M_READSYNC 


TT$M_REMOTE 


TT$M_SCOPE 


TT$M_TTSYNC 


TT$M_WRAP 


Terminal does not receive any broadcast messages. 


Input characters are not echoed on this terminal line (see Section 
5.2.1.5). 


Data must be solicited by a read operation. Data is lost if received in the 
absence of an outstanding read request (if it is unsolicited data). 
Disables type-ahead feature (see Section 5.2.1.5). If this characteristic is 
set, login attempts on this line are disabled. See Section 5.2.3.1 for 
information on modem signal control. 


Read synchronization is enabled. The host explicitly solicits all read 
operations by entering a Ctrl/Q and terminates the operation by 
entering a Ctrl/S. TT$M_READSYNC is not applicable to LAT 
terminals. 


Dialup characteristic is enabled. The terminal returns to local mode 
when a hangup occurs on the terminal line (see Section Section 5.2.3). 
This characteristic cannot be changed; it is only informational. 


Terminal is a video screen display (CRT terminal), for example, the 
VT100 or VT240 terminals. 


The terminal is synchronized to the host system. Output to the terminal 
is controlled by terminal-generated Ctrl/Q or Ctrl/S. TT$M_TTSYNC is 
not applicable to LAT terminals unless TT$M_PASTHRU is set and 
TT$M_TTSYNC is disabled, in which case the LAT session is placed in 
PASSALL mode. 


A carriage-return/line-feed combination should be inserted if the cursor 
moves beyond the right margin. If TT$M_WRAP is not set, no 
carriage-return/line-feed combination is sent. The operating system does 
not support hardware-provided wrapping functions. 


1. Defined by the $TTDEF macro. The prefix can be TT$M_ or TT$V_. TT$M_ is a bit mask whose 
bit corresponds to the specific field; TT$V_ is a bit number. 


Table 5-6 Extended Terminal Characteristics 


Value! 


Meaning 


TT2$M_ALTYPEAHD 
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Alternate type-ahead buffer size is enabled. Use the alternate 
type-ahead buffer size specified during system generation (see Section 
5.2.1.5). Ifa type-ahead buffer already exists for a terminal line, there 
is no effect when this characteristic is set for that line. 
TT2$M_ALTYPEAHD should be set prior to using the terminal, such 
as in the startup command procedure. You can only set 
TT2$M_ALTYPEAHD; this characteristic cannot be cleared until the 
system is rebooted. 
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Table 5-6 Extended Terminal Characteristics (Continued) 
Value! Meaning 
TT2$M_ANSICRT ANSI CRT terminal is enabled. This characteristic is set by the SET 


TERMINAL command. TT2$M_ANSICRT is a subset of the ANSI 
standard with no DIGITAL private escape sequences (see 

Appendix C). It is also a subset of the VT100 family terminals 
(because TT2$M_ ANSICRT is a subset of TT2$M DECCRT) and the 
VT100. Terminals with this characteristic must provide a display of 
at least 24 lines, each with 80 columns. 


TT2$M_APP_KEYPAD Notifies application programs of state to set the keypad to when 
exiting. 
TT2$M_AUTOBAUD Automatic baud rate detection is enabled. This characteristic allows 


the baud rate to be set automatically when you log in. (The baud rate 
is set when one or more carriage returns are entered during the login 
procedure.) Terminals are set to a permanent speed of 9600 baud. If 
TT2$M_AUTOBAUD is specified, the permanent speed must not be 
changed while this characteristic is in use on a given terminal line. 
See Section 5.2.5 for additional information on automatic baud rate 
detection. 


TT2$M_AVO Advanced video is enabled. This characteristic provides the terminal 
with blink, bold, and flashing fields as well as a full screen of 132 
character lines. TT2$M_AVO is set by the SET TERMINAL 
command. Appendix C lists the valid escape sequences for terminals 
with the TT2$M_AVO characteristic. 


TT2$M_BLOCK Block mode is enabled. This characteristic is set by the SET 
TERMINAL command. TT2$M_BLOCK defines additional 
ANSI-defined and DIGITAL private escape sequences (see 
Appendix C). Terminals with this characteristic are capable of local 
editing and block mode transmission (XON/XOFF flow control must 
be honored), and have protected fields. If the terminal is used for 
large amounts of block input, TT2$M_ALTYPEAHD should also be 
specified. 


TT2$M_BRDCSTMBX Mailbox broadcasts messages. Broadcast messages are sent to an 
associated mailbox, if one exists. 
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Table 5-6 Extended Terminal Characteristics (Continued) 


Value! 


Meaning 


TT2$M_COMMSYNC 


TT2$M_DECCRT 


TT2$M_DECCRT2 


TT2$M_DECCRTS3 


TT2$M_DECCRT4 


TT2$M_DIALUP 
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Enables devices such as asynchronous printers to be connected to 
terminal ports. Flow control is handled by EIA modem signals instead 
of XON/XOFF. Setting TT2$M_COMMSYNC activates the DTR and 
RTS signals; data is sent once the DSR and CTS signals are also 
present. If either of these signals is not present, printing stops. When 
both signals are present again, printing resumes. 


Do not set TT2$M_COMMSYNC on a line connected to a modem that 
is intended for interactive use. TT2$M COMMSYNC disables the 
modem terminal characteristic that disconnects a user process from 
the terminal line in case of a modem phone line failure. With 
TT2$M_COMMSYNC set, the next call on the terminal line could be 
attached to the previous user's process. TT2$M_COMMSYNC should 
also not be used in combination with XON/XOFF, TT$M_TTSYNC, or 
TT$M_HOSTSYNC. TT2$M_COMMSYNC and TT$M_MODEM are 
mutually exclusive. 


DIGITAL CRT terminal. This characteristic is set by the SET 
TERMINAL command for all terminals that are upward-compatible 
with VT100 family terminals. TT2$M_DECCRT is a superset of 
TT2$M_ANSICRT. Additional ANSI-defined as well as most 
DIGITAL private escape sequences are allowed for terminals with 
this characteristic (see Appendix C); maintenance modes, VT52 mode, 
and the use of the LED displays are not defined by TT2$M_DECCRT. 
Not all VT100 family terminals implement these features. The 
presence of the advanced video feature cannot be assumed because it 
is a VT100 option. This restricts the use of graphics attributes. 
However, the TT2$M_AVO characteristic can be used to determine 
whether additional graphic attributes are available. 


DIGITAL CRT terminal. This characteristic is set by the SET 
TERMINAL command for all terminals that are upward-compatible 
with VT200 family terminals. TT2$M_DECCRT2 is a superset of 
TT2$M_DECCRT. 


DIGITAL CRT terminal. This characteristic is set by the SET 
TERMINAL command for all terminals that are upward-compatible 
with VT300 family terminals. TT2$M_DECCRT3 is a superset of 
TT2$M_DECCRT2. 


DIGITAL CRT terminal. This characteristic is set by the SET 
TERMINAL command for all terminals that are upward-compatible 
with VT400 family terminals. TT2$M_DECCRT4 is a superset of 
TT2$M_DECCRTS. 


Terminal is a dialup line. Used by LOGINOUT for the disable dialup 
control. 
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Table 5-6 Extended Terminal Characteristics (Continued) 


Value! 


Meaning 


TT2$M_DISCONNECT 


TT2$M_ DMA 


TT2$M_DRCS 


TT2$M_EDIT 


TT2$M_EDITING 


TT2$M_ FALLBACK2 


TT2$M_ HANGUP 


TT2$M_INSERT 


TT2$M_LOCALECHO 


TT2$M_MODHANGUP 


Allows terminal disconnect when a hangup occurs (that is, when 
modem signals are lost, when the DCL commands DISCONNECT or 
CONNECT/CONTINUE are entered, or when the BREAK key is 
pressed on a terminal that has the TT2$M_SECURE characteristic). 
These terminals are created as VTAn:. (Refer to the description for 
the DCL command CONNECT/DISCONNECT in the HP OpenVMS 
DCL Dictionary.) 


Direct memory access (DMA) mode. This characteristic enables the 
use of DMA mode for asynchronous DMA multiplexers. It is ignored 
by non-DMA controllers. 


Terminal supports loadable character fonts. This characteristic is set 
with the DCL command SET TERMINAL/SOFT_CHARACTERS. 


Terminal edit. This characteristic is set by the SET TERMINAL 
command for all terminals that support ANSI-defined advanced 
editing functions. These functions include the ability to insert or 
delete a line and the ability to insert or delete characters in an 
existing line. Terminals with this characteristic are a superset of 
TT2$M_DECCRT. Appendix Clists the valid escape sequences for 
terminals with the TT2$M_EDIT characteristic. 


Line editing is allowed. 


Output is transformed from the 8-bit multinational character set to a 
7-bit ASCII character set on terminals that do not support the 8-bit 
character set (see Appendix C). 


Terminal hangup. Terminal lines connected through modems are 
hung up when a process logs out or is deleted. The state of this 
characteristic cannot be changed unless TT2$M_MODHANGUPFP is 
enabled or the process has either LOG_IO or PHY_IO privilege. 


Sets default mode for insert or overstrike at the beginning of each 
read operation. 


Local echo. This characteristic is used with TT$M_NOECHO. If both 
characteristics are set, only terminators and special control 
characters are echoed. Use of this mode is restricted to command-line 
read operations. Application programs that use the IO$M_NOECHO 
function modifier will not necessarily work if TT2$M_LOCALECHO 
is set. Local echo is also not compatible with line editing 
(TT2$M_EDITING). 


Modify hangup. If specified, TT2$M_HANGUP can be modified 
without privilege. Otherwise, logical or physical I/O privilege is 
required. 
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Table 5-6 Extended Terminal Characteristics (Continued) 


Value! 


Meaning 


TT2$M_PASTHRU 


TT2$M_PRINTER 
TT2$M_REGIS 


TT2$M_SIXEL 


TT2$M_ SECURE 


TT2$M_SETSPEED 


TT2$M_SYSPWD 


TT2$M_XON 


Terminal is in PASTHRU mode; all input and output data is in 7- or 
8-bit binary format (no data interpretation occurs). Data is 
terminated when the buffer is full or when the data that is read 
matches the specified terminator. If the characteristic 
TT$M_TTSYNC is set, Ctrl/S and Ctrl/Q interpretation does occur. 


DIGITAL CRT terminal with a local printer port. 


ReGIS graphics. The terminal supports the ReGIS graphics 
instruction set. 


SIXEL graphics. The terminal supports the SIXEL graphics 
instruction set. 


For use with nonmodem, nonautobaud lines. This characteristic 
guarantees that no process is connected to the terminal after the 
BREAK key is pressed. If TT2$M_SECURE is not set, BREAK is a 
null key. 


Set speed. If specified, either LOG_IO or PHY_IO privilege is 
required to change terminal speed. TT2$M_SETSPEED is not 
supported for LAT devices. 


System password. This characteristic specifies that the login 
procedure should require the system password before the user name 
prompt is displayed. 


XON/XOFF control. Ifa set mode function is performed on a terminal 
in the Ctrl/S state, and if TT2$M_XON is set, output is resumed. 
Users should note that the driver will attempt to resume stopped 
(XOFF) output on the line. However, restarting the output may not be 
successful in all cases. The XON/XOFF feature does not work on all 
terminals, for example, the VT220. 


1. Defined by the $TT2DEF macro. The prefix can be TT2$M_ or TT2$V_. TT2$M_is a bit mask in 
which the bit set corresponds to the specific field; TT2$V_ is a bit number. 

2. If an attempt is made to turn on TT2$V_FALLBACK for a disconnected virtual terminal (_VTAx:) 
or if the Terminal Fallback Facility (TFF) has not been activated, the status code 
SS$_BADPARAM is returned. For more information on TFF, refer to the OpenVMS Terminal 
Fallback Utility (available on the Documentation CD-ROM). 


5.3.1 Terminal Characteristics Categories 


The set mode and set characteristics functions (see Section 5.4.3) and the DCL command SET TERMINAL 
are used to change terminal characteristics. The HP OpenVMS DCL Dictionary describes the SET 


TERMINAL command. 


To customize terminal behavior and usage, the operating system divides terminal characteristics into the 


following categories: 
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Format effectors—The following characteristics allow you to specify terminal-dependent formatting 
requirements: 


TT$M_CRFILL TT$M_EIGHTBIT TT$M_LFFILL 
TT$M_LOWER TT2$M_LOCALECHO TT$M_MECHFORM 
TT$M_MECHTAB TT$M_NOECHO TT$M_SCOPE 
TT$M_WRAP 


Generic terminal capabilities—The following characteristics specify generic terminal features available to 
applications programs: 


TT2$M_ANSICRT TT2$M_AVO TT2$M_BLOCK 
TT2$M_DECCRT TT2$M_DECCRT2 TT2$M_DECCRT3 
TT2$M_DECCRT4 TT2$M_DRCS TT2$M_EDIT 
TT2$M_PRINTER TT2$M_REGIS TT2$M_SIXEL 


Their use allows execution of these programs without knowledge of the actual terminal type. For example, 
a program should check for TT2$M_DECCRT rather than for VT100 or VT101. 


Protocol—The following characteristics control protocols used by the terminal: 
TT$M_ESCAPE TT$M_HALFDUP TT$M_HOSTSYNC 
TT2$M_PASTHRU TT$M_TTSYNC 


System management—The following characteristics, normally set only at system startup, allow the 
system manager to regulate terminal usage: 


TT2$M_ALTYPEAHD TT2$M_AUTOBAUD TT2$M_DIALUP 
TT2$M_DISCONNECT TT2$M_DMA TT2$M_HANGUP 
TT$M_MODEM TT$M_NOTYPEAHD TT2$M_MODHANGUP 
TT2$M_SECURE TT2$M_SETSPEED TT2$M_SYSPWD 


TT2$M_COMMSYNC 


User preference—The following characteristics allow you to customize the terminal operating mode: 


TT2$M_APP_KEYPAD TT2$M_ FALLBACK TT2$M_EDITING 
TT2$M_INSERT TT$M_NOBRDCST 


Miscellaneous—The following characteristics provide greater program control of terminal operations: 


TT2$M_BRDCSTMBX TT$M_MBXDSABL TT2$M_XON 


195 


Terminal Driver 
Terminal Function Codes 


5.4 Terminal Function Codes 


The basic terminal I/O functions are read, write, set mode, set characteristics, sense mode, and sense 
characteristics. All I/O functions can take function modifiers. 


5.4.1 Read 


When a read function code is issued, the user-specified buffer is filled with characters from the associated 
terminal. The operating system provides the following read function codes: 


e JIO$ READVBLK—Read virtual block 
¢ 10$_READLBLK—Read logical block 
e I0$_READPROMPT—Read with prompt 


Read operations are terminated if either of the following two conditions occurs: 


e The user buffer is full. 
e The received character is included in a specified terminator mask (see Section 5.4.1.2). 


The following device- or function-dependent arguments are used with the read function codes. The codes can 
take all six arguments (P1 through P6) on QIO requests. The descriptions for these arguments differ when 
itemlist read operations are performed (see Section 5.4.1.3). 


e P1—tThe starting virtual address of the buffer that is to receive the data read. 


e P2—The size of the buffer that is to receive the data read in bytes. (The system generation parameter, 
MAXBUF, and the terminal driver limit the maximum size of the buffer. The terminal driver will only 
function with buffer sizes less than 32718 bytes.) 


e P3—Read with timeout, timeout count (see Table 5-7, IO$M_TIMED). 
e P4—The read terminator descriptor block address (see Section 5.4.1.2). 


e P5—The starting virtual address of the prompt buffer that is to be written to the terminal; for read with 
prompt operations using the IO$_READPROMPT function code. (This argument is specified as a value 
rather than an address as in the P1 argument.) 


e P6—The size of the prompt buffer that is to be written to the terminal; for read with prompt operations 
using the IO$_ READPROMPT function code. 


In a read with prompt operation, the P5 and P6 arguments specify the address and size of a prompt string 
buffer containing data to be written to the terminal before the input data is read. In a read with prompt 
operation, both read and write operations are performed on the specified terminal. The prompt string buffer 
is formatted like any other write buffer. If cursor position specifiers are supplied, they are not interpreted by 
the driver but passed to the terminal. 


During a read with prompt operation, pressing Ctrl/O (which is turned off at the start of any read operation) 
stops the prompt string. If you press either Ctrl/U or Ctrl/X, the entire prompt string is written out again, and 
the current input is ignored. If you press Ctrl/R, the current prompt string and input are written to the 
terminal. 


Depending on the terminal type and your input, the prompt string can be very simple or quite complex—from 
single command prompts to screen fills followed by input data. HP recommends that prompt strings contain 
only one leading line feed. 
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In PASTHRU mode, data received from the associated terminal is placed in the user buffer as binary 
information without interpretation. (Prompts are not refreshed after a broadcast in PASTHRU mode.) 


5.4.1.1 Function Modifier Codes for Read QIO Functions 


Eight function modifiers can be specified with IO$_READVBLK, IO$_READLBLK, and IO$_READPROMPT. 
Table 5-7 lists these function modifiers and IO$_EXTEND, which is described in Section Section 5.4.1.3. All 
read function modifiers are supported for LAT devices. 


Table 5-7 Read QIO Function Modifiers for the Terminal Driver 


Code 


Consequence 


IO$M_CVTLOW 


IO0$M_DSABLMBX 
I0$M_ESCAPE 


I0$M_EXTEND 


10$M_NOECHO 


IO0$M_NOFILTR 


IO$M_PURGE 


Lowercase alphabetic characters (hexadecimal 61 to 7A) are 
converted to uppercase when transferred to the user buffer or echoed. 
This characteristic is used only for IO$_READLBLK, 
I0$_READVBLK, and I0$_READPROMPT. 


The mailbox is disabled for unsolicited data. 


A valid ANSI escape sequence is recognized as a valid delimiter for 
the read operation. The TT$M_ESCAPRE characteristic is overridden 
by this modifier for the current read operation. 


This characteristic provides additional functionality for read 
operations (see Section 5.4.1.3). Do not specify IO${M_EXTEND with 
other function modifiers. 


Characters are not echoed as they are entered at the keyboard. The 
terminal line can also be set to a “no echo” mode by the set mode 
characteristic TT$M_NOECHO, which inhibits all read operation 
echoing. Setting IO$M_NOECHO also disables line editing. 


The terminal does not interpret Ctrl/U, Ctrl/R, or DEL. They are 
passed to the user. IO$M_NOFILTR explicitly disables line editing. 


The type-ahead buffer is purged before the read operation begins. 
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Table 5-7 Read QIO Function Modifiers for the Terminal Driver (Continued) 
Code Consequence 
IO$M_TIMED The P3 argument specifies the maximum time (seconds) that can 


elapse between characters received from the terminal (the timeout 
value for the operation), only if IO$M_TIMED is specified as a 
modifier on the read function code. 


Note that if you are using a timeout in an item list of a $QIO read to 
a terminal driver, the timeout on an extend read must go into the 
item list. 


Because driver timing operates on a 1-second timer, a 2-second 
timeout must be specified to guarantee a 1-second wait. The timer 
starts when the prompt echo is started. If the read time exceeds the 
time specified in P3, a timeout error (SS$_TIMEOUT) is returned in 
the read IOSB. All input characters received before the read 
operation timed out are returned in the user's buffer. 


A read with timeout operation, in which the timeout value is 0, 
empties the type-ahead buffer into the user buffer until the proper 
termination condition is reached (buffer full, termination character 
detected, or type-ahead buffer empty). The read operation then 
returns the count of characters read and, if a terminator is read, 
SS$_NORMAL; SS$_TIMEOUT is returned if no terminator is read. 
In either case the offset to terminator in the IOSB always indicates 
the number of characters read. 


If a write request is active and there is no prompt string, the read 
request generally times out with zero bytes of data being returned. 


If a read operation is interrupted by either a broadcast write or a 
synchronous write request, the timer operation is restarted. 


IO0$M_TRMNOECHO The termination character (if any) is not echoed. There is no formal 
terminator if the buffer is filled before the terminator is typed. 


5.4.1.2 Read Function Terminators 


The P4 argument to a read QIO function either specifies the terminator set for the read function or points to 
the location containing the terminator set. If P4 is 0, all ASCII characters with a code in the range 0 through 
31 (hexadecimal 0 through 1F), except LF, VT, FF, TAB, and BS, are terminators (see Appendix C). This is the 
RMS standard terminator set. The delete character (hexadecimal 7F) and 8-bit controls in the range 128 
through 159, and 255 (hexadecimal 80 through 9F, and FF) are also terminators. If line editing is enabled, 
only Return, Ctrl/Z, or an escape sequence terminates a read operation. 


If P4 does not equal 0, it contains the address of a quadword that either specifies a terminator character bit 
mask or points to a location containing that mask. (Note that if P4 references an address in a MACRO 
program, a number sign (#) must precede the address; for example, P4=#TMASK.) The quadword has a short 
form and a long form, as shown in Figure 5-3. In the short form, the correspondence is between the bit 
number and the binary value of the character; the character is a terminator if the bit is set. For example, if bit 
0 is set, NULL is a terminator; if bit 9 is set, TAB is a terminator. If a character is not specified, it is not a 
terminator. Since ASCII control characters are in the range 0 through 31, the short form can be used in most 
cases. 
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The long form allows use of a more comprehensive set of terminator characters. Any mask equal to or greater 
than 1 byte is acceptable. For example, a mask size of 16 bytes allows all 7-bit ASCII characters to be used as 
terminators; a mask size of 32 bytes allows all 8-bit characters to be used as terminators for 8-bit terminals. 


If the terminator mask is all zeros, there are no specified terminators. The read operation ends when the 
specified number of bytes (characters) have been transferred to the input buffer. 


Certain control keys will not act as terminators unless IO$M_NOFILTR is specified or the line has the 
TT2$M_PASTHRU characteristic (see Section 5.2.1.2). 


Figure 5-3 Short and Long Forms of Terminator Mask Quadwords 
31 0 
Terminator Character Bit Mask 
31 16 15 0 
LONG: (Not Used) Mask Size in Bytes 


Address of Mask 
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5.4.1.3 Itemlist Read Operations 


Itemlist read operations provide expanded software features to read QIO requests. The operating system 
provides the following combination of function code and modifier: 


IO$ READVBLK!IO$M_EXTEND—Itemlist read virtual block 


No other function modifiers can be specified in an itemlist read request. 


NOTE Itemlist read features supported by the terminal driver are not supported by all DECnet 
terminal emulators. 


The itemlist read function code and modifier combination takes the following device- or function-dependent 
arguments: 


e P1—tThe starting virtual address of the buffer that is to receive the data read. 


e P2—The size of the buffer that is to receive the data read in bytes. If required, the P2 size includes 
additional space for an overflow buffer to hold an escape sequence terminator (see item code 
TRM$_ESCTRMOVPR in Table 5-8). 
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NOTE The IO$_READxBLK and IO$_WRITExBLK are limited by the system parameter 
MAXBUF as well as the terminal driver. The terminal driver will only function with buffer 
sizes less than 32718 bytes. 

e P3—The access mode at which the itemlist is to be probed (optional). 

e P5—The address of the itemlist buffer. 

e P6—The length in bytes of the itemlist buffer. 

P4 is not meaningful for itemlist read operations. P5 points to a series of item descriptors. Figure 5-4 shows 
the format for these descriptors. You cannot repeat the same item code in the same item list. 


Figure 5-4 Itemlist Read Descriptor 


31 16 15 0 


Buffer Address or Immediate Data 


Return Address * 


* Must be zero. 


Itemlist Read P5 Buffer 
ZK-1305-Al 


Table 5-8 lists the item codes that can be specified in the first longword of the item descriptors. 


Table 5-8 Item Codes for Terminal Driver Itemlist Read Operations 
Item Code Meaning 
TRM$_ALTECHSTR Alternate echo string. The buffer length word contains the length of the 


string. The data address word contains the address of the string. The 
alternate echo string is written to the terminal after the first character 
is entered. 


This item code for character validating read mode 
(TRM$K_EM_RDVERIFY) editing only. 


TRM$_EDITMODE Extended editing modes. The immediate data longword specifies 
extended editing mode values. The buffer length word must be zero. The 
following editing modes are supported: 


TRM$K_EM_ DEFAULT Normal read mode. This is the default 
if TRM_EDITMODE is not present in 
the itemlist. 


TRM$K_EM_RDVERIFY Character Validating read mode. See 
“Read Verify Function” on page 204. 
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Table 5-8 Item Codes for Terminal Driver Itemlist Read Operations (Continued) 


Item Code 


Meaning 


TRM$ ESCTRMOVR 


TRM$_FILLCHR 


TRM$_INIOFFSET 


TRM$_INISTRNG 


TRM$_MODIFIERS 


Escape terminator overflow size. Specifies the number of bytes that may 
be used to hold an escape sequence terminator. This number should be 
included in P2, the buffer size argument, in addition to the space 
required for the data to be read. Note that this overflow area is for the 
terminator only; it is not available for user data. 


TRM$_ESCTRMOVPR is useful in preventing partial escape errors, 
which return SS$_PARTESCAPE. This overflow buffer ensures that all 
the characters in an escape sequence terminator will fit in the user 
buffer, thus eliminating the need for additional single-character read 
operations. 


A 2-byte value that indicates the fill and clear character for 
TRM$K_EM_RDVERIFY. The first byte of the immediate data longword 
specifies the clear character; the second byte specifies the fill character. 


This item code is for character validating read mode 
(TRM$K_EM_RDVERIFY) editing only. 


Indicates the character in the initial string where echoing starts. The 
immediate data longword specifies the character. 


Specifies a string to preload into the read buffer (P1). The buffer length 
word contains the length of the string. The data longword contains the 
address of the string. TRM$_INISTRNG must be specified if the edit 
mode is TRM$K_EM_RDVERIFY, and must be the same length as 
specified by TRM$_PICSTRNG. 


Read modifiers. The immediate data longword contains a 32-bit value 
that specifies modifiers to read operations. The read operations are 
defined in $TRMDEF. The buffer length word must be zero. The 
following bits are defined: 


TRM$M_TM_ARROWS The terminal interprets the left and 
right arrow keys 
(TRM$K_EM_RDVERIFY mode only). 
The arrow keys are not put in the 
buffer and do not terminate the read. 
TRM$_ESCTRMOVR must be greater 
than or equal to 5. 


TRM$M_TM_AUTO_TAB This bit creates an autotab mode field 
(TRM$K_EM_RDVERIFY mode only). 


TRM$M_TM_CVTLOW Lowercase alphabetic characters 
(hexadecimal 61 to 7A) are converted 
to uppercase when transferred to the 
user buffer or echoed. 


TRM$M_TM_DSABLMBX The mailbox is disabled for unsolicited 
data and for receiving hangup 
messages. 
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Table 5-8 Item Codes for Terminal Driver Itemlist Read Operations (Continued) 


Item Code Meaning 
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TRM$M_TM_ ESCAPE 


TRM$M_TM_NOCLEAR 


TRM$M_TM_ NOECHO 


TRM$M_TM_NOEDIT 


TRM$M_TM_NOFILTR 


TRM$M_TM_NORECALL 


TRM$M_TM_OTHERWAY 


TRM$M_TM_ PURGE 


TRM$M_TM R_JUST 


TRM$M_TM_TERM_ ARROW 


TRM$M_TM_TERM_DEL 


A valid ANSI escape sequence is 
recognized as a valid delimiter for the 
read operation. 


Fill characters are not replaced with 
clear characters after a nonfill 
character occurs 
(TRM$K_EM_RDVERIFY mode only). 


Characters are not displayed as they 
are entered at the keyboard. 


This bit inhibits advanced editing for 
this read operation. 


The terminal does not interpret DEL, 
Ctrl/U, or Ctrl/R, but passes them to 
you. This characteristic explicitly 
disables line editing. 


This bit inhibits command recall 
(Ctrl/B) by the terminal driver. 


This bit sets left-justify fields to insert 
mode and right-justify fields to 
overstrike mode 
(TRM$K_EM_RDVERIFY mode only). 
TRM$M_TM_TOGGLE must equal 1. 


The type-ahead buffer is purged before 
the read operation begins. 


This bit creates a right-justified field 
(TRM$K_EM_RDVERIFY mode only). 


The read operation is terminated when 
the left arrow key is pressed at the left 
margin or when the right arrow key is 
pressed at the right margin 
(TRM$K_EM_RDVERIFY mode only). 
TRM$M_TM_ARROWS must be 
enabled. 


The read operation is terminated when 
the DELETE key is pressed at the left 
margin (TRM$K_EM_RDVERIFY 
mode only). 
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Item Codes for Terminal Driver Itemlist Read Operations (Continued) 


Item Code Meaning 


TRM$_PICSTRNG 


TRM$M_TM_TOGGLE Enables Ctrl/A to function as a toggle 
key between insert mode and 
overstrike mode 
(TRM$K_EM_RDVERIFY mode only). 
Left-justify insert mode shifts 
characters to the right; right-justify 
insert mode shifts characters to the 
left. Shifted characters are not checked 
for validity in their new positions. 


TRM$M_TM_TIMED TRM$_TIMEOUT specifies the 
maximum time (seconds) that can 
elapse between characters received 
from the terminal; that is, the timeout 
value for the operation. 
TRM$M_TM_TIMED is assumed set if 
TRM$_TIMEOUT is included in the 
itemlist. See the description of 
IO$M_TIMED in Table 5-7. 


TRM$M_TM_TRMNOECHO The termination character (if any) is 
not displayed. There is no formal 
terminator if the buffer is filled before 
the terminator is typed. 


All other bits must be zero. 


Character validation string. The buffer length word contains the length 
of the string, which must be the same as the length specified by 
TRM$_INISTRNG. The data address word contains the address of the 
string. TRM$_PICSTRNG must be specified if the edit mode is 
TRM$K_EM_RDVERIFY. 


Note that this item code is for character validating read mode 
(TRM$K_EM_RDVERIFY) editing only. 


The format of the character validation string is 1 byte per input 
character. Each byte is a bit mask. The following values are provided: 


Value Meaning 
TRM$M_CV_UPPER Uppercase alphabetic 
TRM$M_CV_LOWER Lowercase alphabetic 
TRM$M_CV_NUMERIC Numeric (0-9) 
TRM$M_CV_NUMPUNC Numeric punctuation (+ - .) 
TRM$M_CV_PRINTABLE Printable ASCII character 
TRM$M_CV_ANY Any character 
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Table 5-8 Item Codes for Terminal Driver Itemlist Read Operations (Continued) 


Item Code Meaning 


If no values are set, the corresponding character specified by 
TRM$_INISTRNG is used. Appendix C lists the multinational character 
set. 


TRM$_PROMPT Specifies a prompt string. The buffer length word contains the length of 
the prompt. The data address word contains the address of the prompt 
string. See Section 5.4.1 for information on how carriage control 
specifiers in a prompt string are handled. 


TRM$_TERM The buffer length word determines the format of the nondefault 
terminator mask. If the buffer length word is zero, then the data 
longword is used as a short form mask. If the buffer length word is 
nonzero, then a mask n bytes long is available at the specified address. 


TRM$_ TIMEOUT Read timeout. See the description of IO$M_TIMED in Table 5-7. 


5.4.1.4 Read Verify Function 


When using the read verify function, the terminal driver performs input validation based on character 
attributes. (Read verification bypasses the optionally specified termination mask (TRM$_TERM).) Validation 
is performed one character at a time as data is entered. Invalid characters are not echoed, and cause the read 
operation to complete. It is then up to the application program to handle the error appropriately. 


The initial string describes the initial contents of the input field. This string may consist of data and marker 
characters. The clear character is displayed on the screen for each occurrence of the fill character in the initial 
string buffer. 


The picture string is a string of bytes where each byte corresponds to one character of the field being entered. 
Each byte specifies a mask of legal character types for that character position. If the byte is left as zero, then 
that position is a marker character, and the character from the initial string is echoed for that position. 


For left-justified fields, the prompt data is output to the terminal, followed by an optional number 
(TRM$_INIOFFSET) of initial string characters. Leading marker characters are always output following the 
prompt, leaving the cursor at the leftmost data position. As each character is entered, it is validated and then 
echoed, advancing the cursor position. Additional marker characters are skipped as they are encountered. If 
an input character fails the validation, the read operation is completed with the invalid character as the 
terminator. 


For right-justified fields, the prompt is output and is followed by the initial string. (In general, 
TRM$_INIOFFSET is set to the length of TRM$_INISTRNG for right-justified fields.) The cursor position 
remains one position to the right of the initial string. For proper operation, right-justified fields cannot have 
mixed picture definitions. After each character is input, the entire prompt and input fields are output. 
Therefore, the prompt should include a cursor positioning escape sequence. 


The definition of full field is different for left- and right-justified read operations. For left-justified fields, full 
field is detected when the character corresponding to the last nonmarker position in the picture string has 
been entered. For right-justified fields, full field is detected when a character other than the fill character is 
shifted into the leftmost, nonmarker position in the field. 


If the modifier TRM$M_TM_AUTO_TAB is set in TRM$_ MODIFIERS, then detection of a full field 
terminates the read operation. In the event of autotab termination, the terminator character in the IOSB is 
null. If the autotab option is not selected, then termination occurs when one more character is typed to a full 
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field. Applications can detect this condition when the terminating character index is one character beyond the 
end of the field. The extra character is reported as the terminator. In a left-justified field, the IOSB index to 
the terminator is zero-based; in a right-justified field, this index is one-based. 


If a read verify function is interrupted by an asynchronous write operation, the read verify is completed with 
status SS$_OPINCOMPL. 


No line editing functions other than the delete character function are supported for read verify. 


5.4.2 Write 


Write operations display the contents of a user-specified buffer on the associated terminal. The operating 
system provides the following write I/O functions, which are listed with their function codes: 


¢ 10$_WRITEVBLK—Write virtual block 
e 10$_WRITELBLK—Write logical block 
¢ I0$_WRITEPBLK—Write physical block 


The write function codes can take the following device- or function-dependent arguments: 


e P1—tThe starting virtual address of the buffer that is to be written to the terminal. 


e P2—The number of bytes that are to be written to the terminal. (The system generation parameter, 
MAXBUF, and the terminal driver limit the maximum size of the buffer. The terminal driver will only 
function with buffer sizes less than 32718 bytes.) 


e p4—Carriage control specifier except for write physical block operations. (Write function carriage control 
is described in Section 5.4.2.2.) 


P3, P5, and P6 are not meaningful for terminal write operations. 


In write virtual block and write logical block operations, the buffer (P1 and P2) is formatted for the selected 
terminal and includes the carriage control information specified by P4. 


Unless TT$M_MECHFORM is specified, multiple line feeds are generated for form feeds. The number of line 
feeds generated depends on the current page position and the length of the page. By producing a carriage 
return after the last line feed, a form feed also moves the cursor to the left margin. Multiple spaces are 
generated for tabs if the characteristics of the selected terminal do not include TT$M_MECHTAB (this does 
not apply to write physical block operations). Tab stops occur every eight characters or positions. 


CTDRIVER and Buffered Output 


CTDRIVER, a component of the SET HOST facility, buffers output from remote terminals in order to package 
multiple output requests into a single network transfer. As a result, control is returned early to the user with 
a status of SS$_NORMAL when the output buffer has been filled and successfully queued. 


Note that this output might not be displayed if the user enters an abort character or a Ctrl/O. 


5.4.2.1 Function Modifier Codes for Write QIO Functions 


Five function modifiers can be specified with IO$_WRITEVBLK, IO$_WRITELBLK, and IO$_WRITEPBLK. 
Table 5-9 lists these function modifiers. All write function modifiers are supported for LAT devices. 


Table 5-9 Write QIO Function Modifiers for the Terminal Driver 
Code Consequence 
IO$M_BREAKTHRU Allows breakthrough read regardless of the current active state. 
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Table 5-9 Write QIO Function Modifiers for the Terminal Driver (Continued) 
Code Consequence 

I0$M_CANCTRLO Turns off Ctrl/O (if it is in effect) before the write operation. 
Otherwise, the data cannot be displayed. 

IO$M_ENABLMBX Enables use of the mailbox associated with the terminal for 
notification that unsolicited data is available. 

I0$M_NOFORMAT Allows you to specify write functions without interpretation or 
format; in effect, the terminal line is in a temporary PASTHRU 
mode. 

I0$M_REFRESH If a read operation is interrupted by a write operation (by either a 


write breakthrough! or any other type of write), the terminal 
displays the current read data when the read function is restarted. 


1. Any interruption caused by the execution of the $BRDCST or the $BRKTHRU system service 
broadcasting messages to terminals is referred to as a “write breakthrough.” 


5.4.2.2 Write Function Carriage Control 


The P4 argument is a longword that specifies carriage control. Carriage control determines the next printing 
position on the terminal. P4 is ignored in a write physical block operation. Figure 5-5 shows the P4 longword 
format. 


Figure 5-5 P4 Carriage Control Specifier 
3 2 1 0 
P4: POSTFIX PREFIX (Not Used) | FORTRAN 
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Only bytes 0, 2, and 3 in the longword are used. Byte 1 is ignored. If the low-order byte (byte 0) is not 0, the 
contents of the longword are interpreted as a FORTRAN carriage control specifier. Table 5-10 lists the 
possible byte 0 values (in hexadecimal) and their meanings. 


Table 5-10 FORTRAN Write Function Carriage Control 
Byte 0 Value ASCII Meanin 
(hexadecimal) Character 8 
20 (space) Single-space carriage control (sequence: 
carriage-return/line-feed combination, print buffer contents, 
return!). 
30 0 Double-space carriage control (sequence: 


carriage-return/line-feed combination, 
carriage-return/line-feed combination, print buffer contents, 


return’). 


31 1 Page eject carriage control (sequence: form feed, print buffer 
contents, return). 
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Table 5-10 FORTRAN Write Function Carriage Control (Continued) 
Byte 0 Value ASCII Meanin 
(hexadecimal) Character 8 
2B + Overprint carriage control; allows double printing for 
emphasis or special effects (sequence: print buffer contents, 
return). 
24 $ Prompt carriage control (sequence: carriage-return/line-feed 


combination, print buffer contents). 


All other values Same as ASCII space character: single-space carriage 
control. 


1. A carriage-return/line-feed combination is a carriage return followed by a line feed. 


If the low-order byte (byte 0) is 0, bytes 2 and 3 of the P4 longword are interpreted as the prefix and postfix 
carriage control specifiers. The prefix (byte 2) specifies the carriage control before the buffer contents are 
printed. The postfix (byte 3) specifies the carriage control after the buffer contents are printed. The sequence 
is as follows: 


1. Prefix carriage control 
2. Print 
3. Postfix carriage control 


The prefix and postfix bytes, although interpreted separately, use the same encoding scheme. Table 5-11 
shows this encoding scheme in hexadecimal. 


With several exceptions, Figure 5-6 shows the prefix and postfix hexadecimal coding that produces the 
carriage control functions listed in Table 5-10. Prefix and postfix coding provides an alternative way to 
achieve these controls. 


In the first example in Figure 5-6, the prefix/postfix hexadecimal coding for a single-space carriage control 
(carriage-return/line-feed combination, print buffer contents, return) is obtained by placing the value 1 in the 
second (prefix) byte and the sum of the bit 7 value (80) and the return value (D) in the third postfix byte. 


80 (bit 7 = 1) 
+ D (return) 


8D (postfix = return) 


Table 5-11 Write Function Carriage Control (P4 byte 0 = 0) 


Prefix/Postfix Bytes (Hexadecimal) 


Bit 7 Bits 0O—6 Meaning 
0 0 No carriage control is specified (NULL). 
0 1—7F Bits 0 through 6 are a count of 


carriage-return/line-feed combinations. 
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Table 5-11 Write Function Carriage Control (P4 byte 0 = 0) (Continued) 


Prefix/Postfix Bytes (Hexadecimal) 


Bit 7 Bit 6 Bit 5 Bits 0—4 Meaning 


1 0 0 0—1F Output the single ASCII control character 
specified by the configuration of bits 0 through 4 
(7-bit character set). 


1 1 0 0—1F Output the single ASCII control character 
specified by the configuration of bits 0 through 4, 
which are translated as ASCII characters 128 
through 159 (8-bit character set; see Appendix C). 


1 1 1 O—1F Reserved. 


5.4.3 Set Mode 


Set mode operations affect the operation and characteristics of the associated terminal line. The operating 
system provides two types of set mode functions: set mode and set characteristics. 


The set mode function affects the mode and temporary characteristics of the associated terminal line. Set 
mode is a logical I/O function and requires no privilege. (If you do not have LOG_IO or PHY_IO privilege, the 
terminal driver does not accept a set mode request to a terminal that does not have the extended terminal 
characteristic TT2$M_SETSPEED—even if no request for a change of speed is made. Privilege is not required 
if TT2$M_SETSPEED is set but no attempt to change the speed is made.) The following function code is 
provided: 


e 10$_SETMODE 


The set characteristics function affects the permanent characteristics of the associated terminal line. Set 
characteristics is a physical I/O function and requires the privilege necessary to perform physical I/O. The 
following function code is provided: 
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P4: 


P4: 
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Write Function Carriage Control (Prefix and Postfix Coding) 


(Space) 


Example: Skip 24 lines before printing. 


za 


Sequence: 


Prefix = NL 
Print 
Postfix = CR 


Sequence: 


Prefix = NL, NL 
Print 
Postfix = CR 


Sequence: 


Prefix = FF 
Print 
Postfix = CR 


Sequence: 


Prefix = NULL 
Print 
Postfix = CR 


Sequence: 


Prefix = NL 
Print 
Postfix = NULL 


Sequence: 


Prefix = 24NL 
Print 
Postfix = CR 
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The set mode and set characteristics functions take the following device- or function-dependent arguments if 
no function modifiers are specified: 


P1—Address of characteristics buffer 
P2—Length of characteristics buffer (default length is 8 bytes) 


P3—Speed specifier (bits 0 through 7 = transmit; 8 through 15 = receive) 
P4—Fill specifier (bits 0 through 7 = CR fill count; bits 8 through 15 = LF fill count) 
P5—Parity flags 
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The P1 argument points to a variable-length block, as shown in Figure 5-7. With the exception of terminal 
characteristics, the contents of the block are the same for both the set mode and set characteristics functions. 


Figure 5-7 Set Mode and Set Characteristics Buffers 


31 24 23 16 15 87 0 


Page Length Basic Terminal Characteristics 


P2 = 8 (Default) 


31 24 23 16 15 87 0 


Page Length Basic Terminal Characteristics 


Extended Terminal Characteristics 


P2=12 
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In the buffer, the device class is DC$_TERM, which is defined by the $DCDEF macro. The terminal type is 
defined by the $TTDEF macro; for example, TT$_LA36. The page width is a value in the range of 1 through 
511. The page length is a value in the range of 0 through 255. Table 5-5 lists the values for terminal 
characteristics. Table 5-6 lists the extended terminal characteristics. Characteristics values are defined by 
the $TTDEF and $TT2DEF macros. 


NOTE Make sure that the selected device is a terminal before performing any set mode function, 
particularly when using SYS$INPUT or SYS$OUTPUT. 


The P3 argument defines the device speed, such as TT$C_BAUD_800. The low eight bits specify the transmit 
speed, and the high eight bits specify the receive speed. If no receive speed is specified, the indicated transmit 
speed is used for both transmitting and receiving. If neither the transmit nor the receive speed is specified (P3 
= 0), the baud rate is not changed. The terminal driver ignores the receive speed bits for interfaces that do not 
support split-speed operation. While speeds up to 19.2 K baud can be specified, not all controllers support all 
speed combinations. Refer to the associated hardware documentation to determine which speeds are 
supported by your controller. 


P4 contains fill counts for the carriage-return and line-feed characters. Bits 0 through 7 specify the number of 
fill characters used after a carriage return. Bits 8 through 15 specify the number of fill characters used after a 
line feed. 


P4 is applicable only if TT$M_CRFILL or TT$M_LFFILL is specified as a terminal characteristic for the 
current QIO request; see Table 5-5. 


Several parity flags can be specified in the P5 argument: 
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e TT$M_ALTRPAR—Alter parity. If set, check the state of TT$M_PARITY and TT$M_ODD and, if 
indicated, change the parity. Otherwise, ignore these bits. 


e TT$M_PARITY—Enable parity on terminal line if set, disable if clear. 
e TT$M_ODD—Parity is odd if set. 
e TT$M_ALTDISPAR—Alter dismiss parity errors. If set, check the state of TT$M_DISPARERR. 


e TT$M_DISPARERR—Dismiss parity errors. If this mode is set, a character with a parity error is passed 
to the reader. An error message is not reported. 


NOTE If parity is enabled, the DZ11 generates a parity check bit to detect parity mismatch. 
Unless TT$M_DISPARERR is enabled, parity errors that occur during an I/O read 
operation are fatal to the operation. Parity errors that occur on input characters (that is, 
keys pressed on the keyboard) when no I/O operation is in progress might result in a 
character loss. 


e TT$M BREAK—Generate a break if set. The break is in effect until this bit is turned off. TT$M BREAK 
is supported by the LTDRIVER for terminal servers that support the break capability, such as the 
DECserver 200 and DECserver 500. However, in the case of LAT terminals, the terminal server controls 
the duration of the break. 


e TT$M_ALTFRAME—TIf set, the four low-order bits of P5 become the frame size. Note that the frame size 
is for data bits only and is exclusive of parity. TT$M_ALTFRAME is supported for frame sizes of 7 and 8 
for LAT devices. 


To take the existing parity settings, modify them, and use them in the set mode or set characteristic function, 
move the byte starting at the second nibble of the buffer that is going to be used in the P5 argument. For 
example, the following instructions change the parity from even to odd: 


insv iosb+6, #4, #8, flags 
bisl #ttS$m_altrpar!tt$m_odd!tt$m_parity, flags 


The following instruction then resets the parity to its original state: 
bicl #ttSm_odd!ttSm_parity, flags 
See Section 5.2.5 for information about the SET TERMINAL/FRAME command. 


Application programs that change terminal characteristics should perform the following steps: 


1. Use the IO$_ SENSEMODE function to read the current characteristics. 
2. Modify the characteristics. 
3. Use the set mode function to write back the results. 


4. If the characteristic is intended to be reset when the image exits, the application must perform this 
operation. 


Failure to follow this sequence will result in clearing any previously set characteristic. 


Two stop bits are used only for data rates less than or equal to 150 baud; higher data rates default to one stop 
bit. 


The set mode and set characteristics functions can take the enable Ctrl/C AST, enable Ctrl/Y AST, enable 
out-of-band AST, hangup, set modem, broadcast, and loopback function modifiers that are described in the 
following sections. 
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NOTE If an attempt is made to turn on TT2$V_FALLBACK for a disconnected virtual terminal 
(_VTAx:) or if the Terminal Fallback facility has not been activated, the status code 
SS$_BADPARAM will be returned. For more information on TFF, refer to the OpenVMS 
Terminal Fallback Utility Manual (available on the Documentation CD-ROM). 


5.4.3.1 Hangup Function Modifier 


The hangup function disconnects a terminal that is on a dialup line. (Dialup lines are described in Section 
5.4.3.) The following combinations of function code and modifier are provided: 


e I0$ SETMODE!IO$M_HANGUP 
e I0$_SETCHAR!IO$M_HANGUP 
The hangup function modifier takes no arguments. SS$_NORMAL is returned in the I/O status block. 


NOTE For remote terminals, the hangup function breaks the network connection to the local system, 
ending the remote terminal session. 


5.4.3.2. Enable Ctrl/C AST and Enable Ctrl/Y AST Function Modifiers 


Both set mode functions can take the enable Ctrl/C AST and enable Ctrl/Y AST function modifiers. These 
function modifiers request the terminal driver to queue an AST for the requesting process when you press 
Ctrl/C or Ctrl/Y. The following combinations of function code and modifier are provided: 


e 10$_SETMODE!IO$M_CTRLCAST—Enable Ctrl/C AST 
e 10$_SETMODE!IO$M_CTRLYAST—Enable Ctrl/Y AST 


These function code modifier pairs take the following device- or function-dependent arguments: 


e Pi—Address of the AST service or 0 if the corresponding AST is disabled 
e P2—AST parameter 
e P3—Access mode to deliver AST (maximized with caller's access mode) 


If the respective enabling is in effect, pressing Ctrl/C or Ctrl/Y gains the attention of the enabling process (see 
Table 5-2). 


Enable Ctrl/C and Ctrl/Y AST are one-time enabling function modifiers. After the AST occurs, it must be 
explicitly reenabled by one of the two function code combinations before an AST can occur again. This 
function code is also used to disable the AST. The function is subject to AST quotas. 


You can have more than one Ctrl/C or Ctrl/Y enabled; pressing Ctrl/C, for example, results in the delivery of 
all Ctrl/C ASTs. ASTs are queued and delivered to the user process on a first-in/first-out basis for each access 
mode. However, ASTs are processed in the reverse order of the Ctrl/C AST or Ctrl/Y AST requests that have 

been issued to the terminal driver (on a last-in/first-out basis). 


If no enable Ctrl/C AST is present, the holder of an enable Ctrl/Y AST receives an AST when CtrlI/C is 
pressed; carriage-return/line-feed combination, Ctrl/Y, and Return are echoed. 


Figure 5-8 shows the relationship of Ctrl/C and Ctrl/Y with the out-of-band function. If Ctrl/C or Ctrl/Y is an 
enabled out-of-band character, any out-of-band ASTs specified for this character are delivered. If 
IO$M_INCLUDE function modifier is included in the out-of-band AST request for this character, an enabled 
Ctrl/C or Ctrl/Y AST is also delivered. 
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Enable Ctrl/C AST requests are flushed by the Cancel I/O on the Channel ($CANCEL) system service. Enable 
Ctrl/Y AST requests are flushed by the Deassign I/O Channel ($DASSGN) system service. 


Ctrl/Y is normally used to gain the attention of the command interpreter and to input special commands such 
as DEBUG, STOP, and CONTINUE. Programs that are run from a command interpreter should not enable 
Ctrl/Y. Because ASTs are delivered on a first-in/first-out basis, the command interpreter's AST routine gets 
control first, and might not allow the program's AST to be delivered at all. Programs that require the use of 
Ctrl/Y should use the LIB$DISABLE_CTRL RTL routine to disable DCL recognition of Ctrl/Y. 


See Example 5-4 for a programming example that demonstrates Ctrl/Y and Ctrl/C handling under OpenVMS. 
Section 5.2.1.2 describes other effects of Ctrl/C and Ctrl/Y. 


5.4.3.3 Set Modem Function Modifier 


The set modem function modifier is used in maintenance operations to allow a process to activate and 
deactivate modem control signals. Both set mode and set characteristics functions can take the set modem 
function modifier. The following combinations of function code and modifier are provided: 


e IO0$_SETMODE!IO$M_SET_MODEM!IO$M_MAINT 
e 10$_SETCHAR!IO$M_SET_MODEM!IO$M_MAINT 


NOTE For LAT devices, the set modem field for maintenance operations of the 
I0$M_SET_MODEM!IO$M_MAINT function modifier is unsupported and may return 
unpredictable results. 


These function code modifier pairs take the following device- or function-dependent argument: 


e P1—The address of a quadword block that specifies which modem control signals to activate or deactivate 
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Figure 5-9 shows the format of this block. 


Figure 5-8 Relationship of Out-of-Band Function with Control Characters 
Character Typed 
on Keyboard Deliver 
ma| outofband 
AST. 
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not set, strip bit 7 v 
of character. 
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character in any 
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Yes 


Is this 
an enabled 
outofband 

character 
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set 


OneShot 


Deliver 
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The modem on and modem off fields, in combination or separately, can specify one or more of the following 
values: 
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¢ TT$M_DS_RTS—Request to send (RTS) 
e TT$M_DS_DTR—Data terminal ready (DTR) 


Figure 5-9 Set Mode P1 Block 


31 24 23 16 15 87 0 


ZK0692GE 


e TT$M_DS_SECTX—Transmitted backward channel data (Sec Txd) 


The $TTDEF macro defines the values for these values. These values can only be specified if the terminal 
characteristic TT$M_ MODEM is not set. Otherwise, an error (SS$_ABORT) will result. 


NOTE The set modem function is not supported for remote terminals. The status SS$_DEVREQERR 
is returned in the I/O status block. 


Because the DMF382 does not provide the secondary transmitted data signal (Sec Txd), the 
driver sets the secondary request to send the signal. Users should connect a jumper cable 
between pins 14 and 19 on the DMF32. 


5.4.3.4 Loopback Function Modifier 


The loopback function modifier is used in maintenance operations to place the terminal line in a hardware 
loopback mode. Data transmitted to a line in this mode is returned as receive data. If the controller does not 
support loopback mode or the terminal line has the TT$M_MODEM characteristic set, an error status 
(SS$_ABORT) is returned. Both set mode functions can take the loopback function modifier. 


NOTE The loopback function is not supported for remote terminals. The status SS$_DEVREQERR is 
returned in the I/O status block. 


The following combinations of function code and modifier are provided: 


¢ I0$_SETMODE!IO$M_LOOP!IIO$M_MAINT 
e 10$_SETCHAR!IO$M_LOOP!IO$M_MAINT 


Data transmitted in the loopback mode should only be written in records less than or equal to the size of the 
type-ahead buffer (see Section 5.2.1.5). Programs that use the loopback function modifier should incorporate a 
1-second delay to allow the controller to enable the loopback mode after the request is posted. Write requests 
should also include the IO$M_NOFORMAT function modifier to prevent terminal driver from formatting 
input or output data. 


NOTE The serial line interfaces for the VAX 8200 processor implement an internal loopback bus that 
is common to all four serial lines. The hardware allows all serial lines operating in loopback 
mode to transmit data to the bus at the same time. If more than one serial line writes data to 
the bus, all of the transmitted data is combined and made available to the receiving end of 


215 


Terminal Driver 
Terminal Function Codes 


those same serial lines. Therefore, the received data may be different from the transmitted 
data if more than one serial line is operating in loopback mode at the same time. To prevent 
receiving such spurious data, you must not operate multiple serial lines in loopback mode. 


The operating system provides another function modifier to reset a terminal line previously placed in 
loopback mode. The following combinations of function code and modifier are provided: 


¢ 10$_SETMODE!IO$M_UNLOOP!IO$M_MAINT 
e I0$_SETCHAR!IO$M_UNLOOP!IO$M_MAINT 


Programs that use the unloop function modifier should incorporate a 1-second delay to allow the controller to 
reset the loopback mode after the request is posted. 


NOTE IO$M_LOOP and IO$M_UNLOOP are not supported for LAT devices. 


5.4.3.5 Enable Out-of-Band AST Function Modifier 


The enable out-of-band AST function modifier requests that the terminal driver queue an AST for the 
requesting process when you enter any one of 32 control characters. The following combinations of function 
code and modifier are provided: 


e J0$ SETMODE!IO$M OUTBAND—Enable out-of-band AST 
e 10$ SETCHAR!IIO$M OUTBAND—Enable out-of-band AST 


These function code modifier pairs take the following device- or function-dependent arguments: 


e P1—Address of the AST service or 0 if the AST entered on this channel is to be canceled. (The AST 
parameter will be the out-of-band character.) 


e P2—Address of a character mask with the same format as the short form terminator mask (see Section 
5.4.1.2). 


e P3—Access mode to deliver AST (maximized with the caller's access mode). 
The I0$_SETMODE!IO$M_OUTBAND function can optionally take the following function modifiers: 
¢ IO$M_INCLUDE—Include the character typed in the data stream. 


¢ JO$M_TT_ABORT—Allow current read and write operations to be aborted. (The IOSB for aborted 
operations returns the status SS$_CONTROLC.) 


If an out-of-band AST is in effect, pressing any control character specified in the P2 mask gains the attention 
of the enabling process. Figure 5-8 shows the relationship of the out-of-band function with some of the control 
characters. 


You can have only one out-of-band AST enabled per channel. 

Out-of-band ASTs are repeating ASTs; they continue to be delivered until specifically disabled. Out-of-band 
AST enables are flushed by the Cancel I/O on Channel ($CANCEL) system service. 

5.4.3.6 Broadcast Function Modifier 


The broadcast function modifier allows you to turn on or turn off selected broadcast requester identifiers 
(IDs). The following combination of function code and modifier is provided: 


10$_SETMODE!IO$M_BRDCST 


This function code modifier pair takes the following device- or function-dependent arguments: 
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e P1—A buffer that contains the bits that specify the requester IDs to be broadcast 
e P2—The length of the P1 buffer (default is 8 bytes) 


The first longword of P1 is reserved for use by HP facilities, as shown in Table 5-12. The symbols are defined 
in the system macro library ($BRKDEF). The second longword is for customer use to specify selected bits. If 
any bit is set in the P1 buffer, that particular requester ID is turned off for broadcast. 


Table 5-12 Broadcast Requester IDs 
Bit Meaning 
BRK$C_DCL Disables broadcasts by Ctrl/T 
BRK$C_GENERAL Disables broadcasts by the DCL command REPLY and the 
SYS$BRDCST system service 
BRK$C_MAIL Disables broadcasts by the Mail utility 
BRK$C_PHONE Disables broadcasts by the Phone utility 
BRC$C_QUEUE Disables broadcasts about batch and print queues 
BRK$C_SHUTDOWN Disables broadcasts about system shutdown 
BRK$C_URGENT Disables broadcasts labeled URGENT by the REPLY command 
BRK$C_USERn Disables broadcasts by images associated with the specified value; n 


can be any decimal integer between 1 and 16 


5.4.4 LAT Port Driver QIO Interface 


The LAT port driver (LTDRIVER) accommodates I/O requests from application programs for connections to 
remote devices on one or more terminal servers; for connections to remote services; and for configuring 
LTDRIVER and retrieving configuration information about LTDRIVER. A remote device, such as a printer, 
can be shared in a LAT configuration. Before an application program can access a remote device, the system 
manager must create logical devices and map them to physical devices connected to terminal servers. 
Creating and mapping these logical devices can be done either with the LAT Control Program (LATCP) utility 
or with a $QIO request from a program that has OPER privilege. Once mapped, application programs can 
establish and terminate connections to these remote devices. 


This section describes the capabilities of the QIO interface to the LAT port driver (LTDRIVER). The QIO 
interface allows application programs to access and modify information contained in the LTDRIVER data 
structures and to initiate events and obtain status information. You must use these QIO functions to 
establish a connection to a remote device or service from an application program. HP does not support any 
other methods of connection. 


The LTDRIVER responds to TEST SERVICE commands issued at terminal servers that support the TEST 
SERVICE command, such as the DECserver 200 and DECserver 500 servers. 


LAT devices can use all read and write function modifiers listed for the terminal driver function codes except 
those modifiers that apply to modems (see Sections Section 5.4.1 and Section 5.4.2). 


The operating system does not support the following set mode or set characteristics function code modifiers 
for LAT devices: 


e IO$M_LOOP 
e I0$M_UNLOOP 
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e TT$M_ALTRPAR 

e TT$M_ALTFRAME 

¢ TT$M_MODEM 

e TT$M_READSYNC 

e TT2$M_SETSPEED 

With LAT devices, the terminal server, rather than the host, handles flow control to the physical device. A 
separate flow control mechanism exists between the server and the host. 

5.4.4.1 LAT Port Types 

QIO functions can be used to create the following LAT port types: 


e Application Port. This type of port can be used to connect to a remote device (typically a printer) on a 
terminal server or to a dedicated port on another LAT service node. This is the default port type. See 
Section 5.4.4.5 for a description of programming an application port. 


e Dedicated Port. This type of port specifies that the logical port on your node is dedicated to an application 
service. When users on a terminal server (or on another node that supports outgoing connections) request 


a connection to this service name, they are connected to a dedicated port. See Section 5.4.4.6 for a 
description of programming a dedicated port and application service. 


e Forward Port. This type of port is used for outgoing LAT connections (to remote services) and is created by 


assigning a channel to the LAT template device _LTAO: with the $ASSIGN system service. 


QIO functions can also be used to configure and read information about these ports; for more information: 


— See Section 5.4.4.3 for a description of configuring a LAT port 


— See Section 5.4.4.4 for a description of reading configuration information about a LAT port 


— See Section 5.4.4.7 for a description of programming a forward port in order to make a connection to a 


LAT service 


5.4.4.2 LAT Port Driver Functions 


The operating system provides the following combinations of function code and modifier: 


e JO$_TTY_PORT!IO$M_LT_CONNECT. Requests that the LAT port driver make a connection to a remote 


device on a server (or dedicated port on another LAT service node) or to a remote service, depending on 
whether the port is an application port or a forward port respectively. For dedicated ports, this QIO 


completes when an incoming connection to the port is established. See Section 5.4.4.5 for a description of 


programming an application port, Section 5.4.4.6 for a description of programming a dedicated port, and 
Section 5.4.4.7 for a description of programming a forward port. 


e I0$_TTY_PORT!IO$M_LT_DISCON. Depending on the port type, requests that the LAT port driver 
terminate the LAT connection to the remote device, service, or local application service. 


IO0$M_FLUSH_DATA can be specified in the P2 argument to IO$M_LT_DISCON. The flush flag indicates 


that any data not delivered to the remote device is to be flushed when the disconnect is issued. 


e I0O$_TTY_PORT!IO$M_LT_SETMODE. Requests that the LAT port driver create or configure a LAT 
entity. See Section 5.4.4.3 for more information. 


e 10$_TTY_PORT!IO$M_LT_SENSEMODE. Requests that the LAT port driver return configuration 
information about a LAT entity. See Section 5.4.4.4 for more information. 
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5.4.4.3 Creating and Configuring LAT Entities 


The LAT SETMODE $QIO function (IO$_TTY_PORT!IO$M_LT_SETMODE) is used to create, delete, and 
modify LAT nodes, services, ports, and links. 


Creation, deletion, or modification of any entity requires the OPER privilege. 


The LAT SETMODE $QIO function accepts four arguments: P1, P2, P3, and P4. P1 is the address of an item 
list; P2 is the length of this item list. 


P3 specifies the type of entity to which the SETMODE operation applies. The entity type can be one of five 
types: 


¢ Node (LAT$C_ENT_NODE). Only the local node name may be specified, with the exception of a 
SETMODE itemlist containing no item codes other than LAT$_ITM_COUNTERS. 


e Service (LAT$C_ENT_SERVICE). Only local service names may be specified, with the exception of a 
SETMODE itemlist containing no item codes other than LAT$_ITM_COUNTERS. 


e Link (LAT$C_ENT_ LINK). The data link associated with the LAN. 
e Port (LAT$C_ENT_PORT). 


¢ Queue Entry (LAT$C_ENT_QUEUE_ENTRY). Indicates queue entry entities. When this entity is used, 
the only valid SETMODE operation is delete. 


The value for the entity type occupies the low-order 16 bits (bits 0--15) of the P3 parameter. For all four entity 
types, bits 16--19 are used as a status field to indicate the expected current status of the entity. These bits are 
used to decide whether the entity needs to be created before its characteristics are set. The possible values for 
this field are: 


e LAT$C_ENTS_OLD—The entity must already exist. An SS$_NOSUCHDEYV error is returned if the 
entity does not exist. 


e LAT$C_ENTS_NEW—The entity must be created. An SS$_DUPLNAM error is returned if the entity 
already exists. 


e LAT$C_ENTS_UNK—If the entity does not exist, it is created. If it does exist, its characteristics are 
modified. 


e LAT$C_ENTS_DEL—TIf the entity exists, delete it. Otherwise, an SS$_NOSUCHDEYV error is returned 
and the item list is not used. 


P4 may contain the address of an entity name string descriptor. If this parameter is omitted (contains a 0 or 
the address of a descriptor that points to an empty buffer), a default may be used in some cases. The defaults 
for each entity type are as follows: 


e LAT$C_ENT_NODE—The local node. 
e LAT$C_ENT_SERVICE—No default; you must specify the service name. 
e LAT$C_ENT_LINK—The string LAT$LINK. 


e LAT$C_ENT_PORT—The device name associated with the currently assigned channel (the CHAN 
parameter of the $QIO function). 


SETMODE can return the following status codes: 
e SS$_NOPRIV—No privilege to complete the desired operation. 
e S§S$_ACCVIO—Part of the argument list or itemlist is not addressable. 


e SS$ _BADPARAM—One of the parameters in the itemlist is in error. If this value is returned, the second 
longword of the IOSB contains the item code of the parameter in error. 
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SETMODE Item Codes 


Each item in the itemlist consists of a one-word (16-bit) item code, followed by a value associated with the 
item. 


Item codes in which the bit named LAT$V_STRING is zero take a longword value. The associated value is 
contained in the longword immediately following the item code in the itemlist. Item codes in which this bit is 
1 take a counted string for their value. The byte immediately following the item code contains a byte count, 
which describes the length of the string that immediately follows it. 


If you set bit LAT$V_CLEAR in the item code to 1, the current value associated with the item code is cleared 
or set to its default value. In this case, the actual value specified in the itemlist is ignored, although the byte 
count field skips to the next item in the itemlist. 


Figure 5-10 shows an example of a SETMODE itemlist. 


Figure 5-10 Example SETMODE Itemlist 
31 16 15 0 


LAT$C_ON LAT$_ITM_STATE 


LAT$_ITM_KEEPALIVE_TIMER 


LAT$_ITM_USER_GROUPS 
LAT$_OUTGOING_SES_LIMIT 9 1 


5 
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This SETMODE itemlist is the P1 parameter for a $QIO SETMODE function on the local node. P4 is omitted, 
and P3 is #LAT$C_ENT_NODE!$C_ENTS_OLD@16>. P2 is the length of the itemlist (52). A $QIO 
SETMODE function for this itemlist would perform the following operations: 


1. Set the state of the node to on. 

2. Set the LAT keepalive timer to 40 seconds. 

3. Set the node identification to LTC CLUSTER. 

4. Set the LAT circuit timer to 160 milliseconds. 

5. Enable LAT outbound connections. 

6. Turn on user groups 2, 8, 10, 11, 12, 16, and 19. LAT$_ITM_USER_GROUPS is represented by a bit field. 
7 


. Set the outgoing session limit to five sessions. 
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For each entity type, only a subset of item codes may be set. Table 5-13 lists the item codes that may be set for 


the LAT$C_ENT_NODE entity type. 


Table 5-13 LAT$C_ENT_ NODE Item Codes 


Item Code 


Meaning 


LAT$_ITM_ STATE 


LAT$_ITM_CIRCUIT_TIMER 


LAT$_ITM_CPU_RATING 


LAT$ ITM _DEVICE_SEED 


LAT$_ITM_KEEPALIVE_TIMER 


LAT$_ITM_ MULTICAST TIMER 


LAT$_ITM_NODE_LIMIT 


LAT$ ITM _RETRANSMIT_ LIMIT 


LAT$ ITM _SERVER_MODE 


Operating state of the LAT protocol. The following values are 
allowed: 


LAT$C_OFF Turns off LAT protocol processing. No 
new connections allowed in either 
direction. Existing connections are 
terminated immediately. This is the 
default. 


LAT$C_SHUT Disallows new LAT connections in either 
direction. Existing connections are 
allowed to remain active. 


LAT$C_ON Turns on LAT protocol processing. 


Circuit timer value in milliseconds. Valid values are 10 to 1000 
milliseconds. The default is 80 milliseconds. 


CPU rating. Valid values are 0 to 100. If this value is 0, then the 
CPU rating value is not used in the rating calculation. Refer to 
the HP OpenVMS System Management Utilities Reference 
Manual for a complete description of this feature. 


Overrides the default lower boundary for new LTA devices. Valid 
values are 0 to 9999; the default is 0. Refer to the HP OpenVMS 
System Management Utilities Reference Manual for more 
information on this feature. 


Keepalive timer value in seconds. Valid values are 10 to 255 
seconds. The default is 20 seconds. 


Multicast timer value in seconds. Valid values are 10 to 180 
seconds. The default is 60 seconds. 


Maximum number of nodes in LAT database. The default is 0, 
where the maximum is determined by system resources. 


LAT retransmit limit. Valid values are 4 to 120 retransmissions. 
The default is 8 retransmissions. 


Controls whether the node allows the use of the MASTER side of 
the LAT protocol for outbound connections. Valid values are: 


LAT$C_DISABLED _ Server mode disabled (this is the default). 
LAT$C_ENABLED Server mode enabled. 
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Table 5-13 LAT$C_ENT_NODE Item Codes (Continued) 


Item Code 


Meaning 


LAT$_ ITM _SERVICE_RESPONDER 


LAT$_ITM_OUTGOING_SES_LIMIT 


LAT$_ITM_ INCOMING _SES_LIMIT 


LAT$_ ITM CONNECTIONS 


LAT$_ITM NODE_NAME 


LAT$_ITM_ IDENTIFICATION 


LAT$_ ITM _SERVICE_GROUPS 
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Indicates whether the node is to respond to service inquiries 
originating from a remote system. These inquiries are not 
necessarily directed at services being offered by the node. Refer to 
the HP OpenVMS System Management Utilities Reference 
Manual for a complete description of this feature. Valid values 
are: 


LAT$C_DISABLED _ Service responder disabled (this is the 
default). 


LAT$C_ENABLED _ Service responder enabled. 


Maximum number of outgoing LAT sessions. A value of 0, which 
is the default, indicates that the limit is determined by system 
resources. 


Maximum number of interactive LAT sessions. A value of 0, 
which is the default, indicates that the limit is determined by 
system resources. 


Controls whether inbound connections can be accepted. Valid 
values are: 


LAT$C_DISABLED Inbound connections disabled. 


LAT$C_ENABLED Inbound connections enabled (this is the 
default). 


Causes the LAT node name to be set to the given name. This item 
code may be specified only if the entity status field of the P3 
parameter is LAT$C_ENTS_NEW;; otherwise, a 
LAT$_ENTNOTFOU error results. 


Node identification string. The default is the translation of 
SYS$ANNOUNCE. 


Specifies a default service group code bit mask. This mask is then 
used when creating new local services. The default is group code 0 
enabled and all others disabled when the LAT software is 
initialized. 

Note that the use of the LAT$V_CLEAR bit is an exception for 
this parameter code. If you clear bit LAT$V_CLEAR, group codes 
corresponding to the group code mask, as specified in the itemlist, 
are set. Alternatively, if you set LAT$V_CLEAR, group codes 
corresponding to the group code mask, as specified in the itemlist, 
are cleared. 
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Table 5-13 LAT$C_ENT_NODE Item Codes (Continued) 


Item Code 


Meaning 


LAT$_ ITM_USER_GROUPS 


LAT$_ITM_COUNTERS 


LAT$_ITM_ MAXIMUM_UNITS 


LAT$ ITM _HI CIRCUITS! 


LAT$ ITM _CUR_CIRCUITS! 
LAT$ ITM MAX CIRCUITS! 


LAT$ ITM_HI SESSIONS! 


LAT$ ITM _CUR_SESSIONS! 
LAT$ ITM MAX SESSIONS! 


LAT$ ITM HI OUT_QUEUE! 


LAT$_ITM_CUR_OUT_QUEUE! 


LAT$_ITM_ MAX OUT_QUEUE! 


LAT$_TIM_HI_IN_ QUEUE! 


LAT$_ITM_CUR_IN_QUEUE! 


LAT$_ITM_CUR_IN QUEUE! 


LAT group codes to be used when attempting outbound 
connections using the MASTER side of the LAT protocol. The 
default is all group codes disabled when the LAT software is 
initialized. 

Note that the use of the LAT$V_CLEAR bit is an exception for 
this parameter code. If you clear bit LAT$V_CLEAR, group codes 
corresponding to the group code mask, as specified in the itemlist, 
are set. Alternatively, if you set LAT$V_CLEAR, group codes 
corresponding to the group code mask, as specified in the itemlist, 
are cleared. 


Node counters block. Allows for zeroing of all node counters. This 
item code may be specified only if the entity status field of the P3 
parameter is LAT$C_ENTS_OLD and the LAT$V_CLEAR bit is 
set. Violating either of these two rules results in a returned 
status of SS$_ BADPARAM. 


Maximum unit number. Sets the highest value for a LTA unit 
number. Must be between 1 and 9999; defaults to 9999. 


Indicates the highest number the resource attained since the host 
was initialized for LAT connections to node. 


Indicates current count of active connections to node. 
Indicates maximum allowed virtual circuits to node. 


Indicates highest number the resource attained since the host 
was initialized for LAT sessions. 


Indicates current number of active sessions. 
Indicates maximum possible sessions. 


Indicates highest number the resource attained since the host 
was initialized of outgoing queued connect requests. 


Indicates current count of outgoing queued connect requests. 


Indicates maximum number of simultaneous outgoing queued 
connect requests. 


Indicates highest number the resource attained since the host 
was initialized of incoming queued requests. 


Indicates current number of entries in the incoming connect 
queue. 


Indicates maximum number of entries allowed on the incoming 
connect queue. 
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Table 5-13 LAT$C_ENT_NODE Item Codes (Continued) 


Item Code 


Meaning 


LAT$_ITM_HI_SAMS_QUEUED! 


LAT$_ITM_CUR_SAMS_QUEUED! 


LAT$_ITM_MAX_SAMS_QUEUED! 


LAT$_ITM_HI_SOL_QUEUED! 


LAT$_ITM_CUR_SOL_QUEUED 


LAT$_ITM_MAX_SOL_QUEUED! 


LAT$ ITM HI AVAIL Svcs! 


LAT$ ITM _CUR_AVAIL SVCS! 


LAT$ ITM MAX AVAIL SVCS! 


LAT$ ITM_HI_ REACH NODES! 
LAT$ ITM _CUR_REACH NODES! 


LAT$ ITM MAX REACH NODES! 


LAT$_ITM_HI_LCL_SVCS 


LAT$ ITM _CUR_LCL_Svcs! 


LAT$ ITM MAX LCL Svcs! 


LAT$ ITM DISCARDED NODES! 
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Indicates highest number the resource attained since the host 
was initialized of outstanding, unprocessed service 
announcement messages by LATACP. 


Indicates current number of outstanding, unprocessed service 
announcement messages on LATACP's queue. 


Indicates maximum number of outstanding, unprocessed service 
announcement messages allowed on LATACP's queue. If this 
limit is ever reached, subsequent service announcement 
messages are not delivered or processed by LATACP. 


Indicates highest number the resource attained since the host 
was initialized of outstanding, unprocessed solicit information 
messages by LATACP. 


Indicates current number of outstanding, unprocessed solicit 
information messages on LATACP's queue. 


Indicates maximum number of outstanding, unprocessed solicit 
information messages allowed on LATACP's queue. If this limit is 
ever reached, subsequent solicit information messages are not 
delivered or processed by LATACP. 


Indicates highest number the resource attained since the host 
was initialized by the number of available services in LATACP 
database. 


Indicates count of currently available LAT services in LATACP 
database. 


Indicates maximum number of available services possible in 
LATACP database. 


Indicates highest number the resource attained since the host 
was initialized of reachable nodes in LATACP database. 


Indicates current number of reachable nodes in LATACP 
database. 


Indicates maximum number of nodes allowed in LATACP 
database. 


Indicates highest number the resource attained since the host 
was initialized of locally offered services. 


Indicates current count of locally offered service. 
Indicates maximum number of locally offered services. 


Indicates number of discarded service announcement messages. 
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Table 5-13 LAT$C_ENT_NODE Item Codes (Continued) 


Item Code 


Meaning 


LAT$ ITM_SERVICE_CLASSES! 


LAT$_ITM_LARGE_BUFFERS 


LAT$_ITM_ ANNOUNCEMENTS 


Indicates returned service class bit mask for supported service 
classes on node. It is returned for bothlocal and remote nodes. If 
service class 1 is enabled, then bit 1 is set in this mask. When bit 
setting equals 1, this indicates the corresponding service class for 
that bit is enabled. That is, when bit 3 equal 1, then service class 
3 is enabled. 


Indicates in Boolean logic whether or not the LAT software is 
using large packet support by default. 


Indicates in Boolean logic whether or not the LAT software is 
transmitting LAT service advertisement messages. 


1. Alpha and 164 specific 


Table 5-14 lists the item codes that may be set for the LAT$C_ENT_SERVICE entity type. 
Table 5-14 LAT$C_ENT_SERVICE Item Codes 


Item Code 


Meaning 


LAT$_ITM_RATING 
LAT$ IETEM_ IDENTIFICATION 


LAT$_ ITM SERVICE_TYPE 


LAT$_ITM_COUNTERS 


LAT$_ ITM PASSWORD! 


Static LAT service rating. The default is the dynamic rating 
calculation. Static ratings can be between 0 and 255. 


Service identification string. The default is the translation of 
SYS$ANNOUNCE. 


Defines the type of service. Valid values are: 
LAT$C_ST_GENERAL Creates a general timesharing service. 


LAT$C_ST_APPLICATION Creates a special application service 
that must then be associated with 
ports dedicated to accepting 
connections to this service (dedicated 
ports). 


LAT$C_ST_ LIMITED! Indicates that the service is limited. 


Service counters block. Allows for zeroing of all service counters. This 
item code may be specified only if the entity status field is 
LAT$C_ENTS_OLD and the LAT$V_CLEAR bit is set. Violating 
either of these two rules results in a returned status of 
SS$_BADPARAM. 


Indicates that if a value of LAT$C_ENABLED is indicated, then the 
service is password protected. Indicates that if a value of 
LAT$C_DISABLED is indicated, then the service is not password 
protected. 
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Table 5-14 LAT$C_ENT_SERVICE Item Codes (Continued) 


Item Code 


Meaning 


LAT$_ITM_LIM_PORT_BLOCK! 


Indicates a subblock contained in an itemlist, which has a list of 
limited ports associated with the named service. This subblock may 
be repeated several times; that is, once for each limited LAT device 
associated with the specified service. 


1. Alpha and 164 specific 


Table 5-15 lists the item codes that may be set for the LAT$C_ENT_LINK entity type. 
Table 5-15 LAT$C_ENT_LINK Item Codes 


Item Code 


Meaning 


LAT$_ITM_ STATE 


LAT$_ITM_DEVICE_NAME 


LAT$_ITM_DECNET_ADDRESS 


LAT$_ ITM COUNTERS 


Operating state of the LAT protocol. Valid values are: 


LAT$C_OFF Turns off LAT protocol processing. No new 
connections allowed in either direction. 
Existing connections are terminated 
immediately. 


LAT$C_SHUT Disallows new LAT connections in either 
direction. Existing connections are allowed to 
remain active. 


LAT$C_ON Turns on LAT protocol processing. This is the 
default. 


The name of the local area network (LAN) device to be used for this 
link. The default is hardware-dependent. 


Specifies whether to use the DECnet address when starting the LAT 
protocol on the LAN controller associated with this link. Valid values 
are: 


LAT$C_DISABLED DECnet address use disabled. 


LAT$C_ENABLED DECnet address use enabled (this is the 
default). 


Link counters block. Allows for zeroing of all link counters. This item 
code may be specified only if the entity status field is 
LAT$C_ENTS_OLD and the LAT$V_CLEAR bit is set. Violating 
either of these two rules results in a returned status of 
SS$_BADPARAM. 
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Table 5-16 lists the item codes that may be set for the LAT$C_ENT_PORT entity type. 
Table 5-16 LAT$C_ENT_PORT Item Codes 


Item Code 


Meaning 


LAT$_ITM_PORT_TYPE 


LAT$_ITM_QUEUED 


LAT$_ITM_SERVICE_CLASS 


LAT$_ ITM DISPLAY NUMBER 


LAT$_ITM_TARGET_NODE_NAME 


LAT$_ITM_TARGET_SERVICE_NAME 


Type of port. Valid values are: 


LAT$C_PT_APPLICATION Application port for 
solicited connections. 
LAT$C_PT_DEDICATED Dedicated port 


associated with a local 
application service. 


LAT$C_PT_LIMITED! Indicates that the port 
type is limited. 


Controls whether the solicited connection requests queued or 
nonqueued access. Valid values are: 


LAT$C_DISABLED Queued access disabled. 


LAT$C_ENABLED Queued access enabled 
(this is the default). 


Controls the class driver that the LAT driver communicates 
with when a connection is established. This item code can be 
used only with an entity status of LAT$C_ENTS_NEW. 
Therefore, the service class must be specified when the device 
is created. An attempt to change the service class of an 
existing device returns SS$_BADPARAM. Valid values are: 


LAT$C_SERVCLASS_INTERACT _ Service class 1, 


IVE TTDRIVER (this is the 
default). 

LAT$C_SERVCLASS_XTRANSPO | Service class 3, X 

RT Protocol. 

LAT$C_SERVCLASS_FONT Service class 4, X fonts. 


For X devices, this is the binary value of the display number, 
which may need to be transmitted in some LAT messages. 
Values range from 0--255, with a default of 0. This item code 
has meaning only when used with service classes 3 and 4 
(LAT$C_SERVCLASS_XTRANSPORT AND 
LAT$C_SERVCLASS_FONT). 


Target node name for connection. This parameter must be 
specified for application ports and may optionally be specified 
for forward ports. 


Target service name for connection. This parameter must be 
specified for forward ports and may optionally be specified for 
application ports. For dedicated ports, this parameter specifies 
the local application service to which the port should be 
associated. 
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Table 5-16 LAT$C_ENT_ PORT Item Codes (Continued) 
Item Code Meaning 
LAT$_ITM_TARGET_PORT_NAME Target port name for connection. This parameter may 


optionally be specified for application ports or forward ports; it 
is ignored for all other kinds of ports. 


LAT$_ITM_SERVICE_PASSWORD Password string for remote service on forward ports. This 
parameter must be specified to access services that are 
protected with a password. This parameter is ignored if it is 
specified for a service that is not protected with a password. 


LAT$ ITM DIALUP! Indicates if an LTA device tells a remote node that the 
connection is coming from a dialin source. Possible values are 
LAT$C_ENABLED or LAT$C_DISABLED. 


LAT$ ITM_AUTOPROMPT! Indicates if a connect request has autoprompt enabled. 
~ a Possible values are LAT$C_ENABLED or LAT$C_DISABLED. 


1. Alpha and 164 specific. 


5.4.4.4 Obtaining Information About LAT Entities 


The LAT SENSEMODE $QIO function (IO$_TTY_PORT!IO$M_LT_SENSEMODE) is used to obtain 
information about LAT nodes, services, ports, and links. 


The LAT SENSEMODE $QIO function accepts four arguments: P1, P2, P3, and P4. P1 is the address of a 
buffer into which information about the desired entity is returned. The information is returned in the form of 
an item list. Unlike system services such as $GETDVI or $GETJPI, you do not select which items of 
information are returned. P2 is the length of the buffer specified in P1, in bytes. The number of bytes of 
information returned in the P1 buffer is returned in IOSB+2. 


P83 specifies the type of entity to which the SENSEMODE operation applies. The entity type can be one of five 
types: 

¢ Node (LAT$C_ENT_NODE). Node, including the local node. 

¢ Service (LAT$C_ENT_SERVICE). Service, including local services. 

e Link (LAT$C_ENT_LINK). Data link associated with the LAN. 

¢ Port (LAT$C_ENT_PORT). 

¢ Queue Entry (LAT$C_ENT_QUEUE_ENTRY). Indicates queue entry entities. 


The value for the entity type occupies the low-order 16 bits (bits 0--15) of the P3 parameter. Bits 16--23 are 
used as a flag field. Two bits are currently defined within this field: LAT$V_SENSE_NEXT and 
LAT$V_SENSE_FULL. If the LAT$V_SENSE_NEXT bit is 0, information about the current entity described 
by the P3 and P4 parameters is returned to the user; if this bit is 1, information about the next entity that 
logically follows the one described by P4 is returned. If LAT$V_SENSE_FULL is 0, only those item codes 
marked SUMMARY in the following tables are returned; if this bit is 1, all item codes that describe the entity 
specified by the P3 and P4 parameters are returned. 


P4 may contain the address of an entity name string descriptor. If this parameter is omitted (contains a zero 
or the address of a descriptor that points to an empty string) and the LAT$V_SENSE_NEXT bit is set, 
information about the first entity that matches the entity type supplied by P38 is returned. 


If P4 is omitted and the LAT$V_SENSE_NEXT bit is 0, a default entity name may be used in some cases. The 
defaults for each entity type are as follows: 
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e LAT$C_ENT NODE—The local node. 
e LAT$C_ENT_SERVICE—No default; you must specify the service name. 
e LAT$C_ENT_LINK—The string LAT$LINK. 


e LAT$C_ENT_PORT—The device name associated with the currently assigned channel (the CHAN 
parameter of the $QIO function.) 


SENSEMODE can return the following failure return codes: 


e SS$_NOPRIV—No privilege to complete the desired operation 
e SS$_ACCVIO—Part of the argument list or item list is not addressable 


5.4.4.4.1 SENSEMODE Item Codes 


Each item in the itemlist starts with a one-word (16-bit) item code that describes the type of information 
contained in the item. The item code is followed by a value associated with the item. 


Item codes in which the bit named LAT$V_STRING is 0 take a longword value. The associated value is 
contained in the longword immediately following the item code in the itemlist. Item codes in which this bit is 
1 take a counted string for their value. The byte immediately following the item code contains a byte count, 
which describes the length of the string that immediately follows it. 


Table 5-17 lists the item codes that are returned for the LAT$C_ENT_NODE entity type. Item codes noted as 
LOCAL are returned only if the information being returned is for the local node. Item codes noted as 
REMOTE are returned only if the information being returned is for a remote node. Item codes noted as BOTH 
are returned for both types of nodes. 


Table 5-17 LAT$C_ENT_NODE Item Codes 
Item Code Meaning 

LAT$_ITM_NODE_NAME (BOTH, LAT node name for the node. 

SUMMARY) 

LAT$_ITM_IDENTIFICATION Node identification string. 

(BOTH, SUMMARY) 

LAT$_ITM_NODE_TYPE (BOTH, Type of node. Possible values are: 

SUMMARY) 
LAT$C_NT_LOCAL Node is local node. 
LAT$C_NT_REMOTE Node is remote node. 

LAT$_ITM_STATE Operating state of the LAT protocol. Possible values are: 

(LOCAL,SUMMARY) 
LAT$C_ON New connections are allowed and 

the LAT protocol is running. 

LAT$C_OFF New connections are not allowed. 


The LAT protocol is not running. 
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Table 5-17 LAT$C_ENT_NODE Item Codes (Continued) 


Item Code 


Meaning 


LAT$_ITM_NODE_STATUS 
(REMOTE, SUMMARY) 


LAT$_ITM_CONNECTED_COUNT 
(REMOTE, SUMMARY) 


LAT$_ITM_SERVICE_GROUPS 
(BOTH) 


LAT$_ITM_PROTOCOL_VERSION 
(BOTH) 


LAT$_ITM_ DATALINK_ 
ADDRESS (REMOTE) 


LAT$_ ITM _NODE_LIMIT 


LAT$ ITM _RETRANSMIT_ 
LIMIT 


LAT$_ITM_MAXIMUM_UNITS 
(LOCAL) 


LAT$_ITM_SERVER_MODE 
(LOCAL) 
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No new connections are allowed. 
Currently active connections are 
still maintained. The LAT protocol 
remains running only until the last 
active session is disconnected, at 
which time the node is placed in the 
OFF state. 


Current status of remote node. This item code is present only if a 
LAT virtual circuit does not currently exist between the local 
node and this remote node. Possible values are: 


LAT$C_REACHABLE Remote node is reachable. 
LAT$C_UNREACHABLE Remote node is unreachable. 
LAT$C_UNKNOWN Remote node status is unknown. 


Number of LAT sessions from the local node to this remote node. 
This item code replaces the LAT$_ITM_NODE_STATUS item 
code for remote nodes to which a LAT virtual circuit currently 
exists. 


A bit mask of LAT group codes that are serviced by the node. 


LAT protocol version string. 


LAN address uesed by the node. 


Maximum number of nodes in LAT database. The default is 0, 
where the maximum is determined by system resources. 


LAT retransmit limit. Possible values are 4 to 120 
retransmissions. The default is 8 retransmissions. 


Maximum LTA unit number. 


Controls whether the node allows the use of the MASTER side of 
the LAT protocol for outbound connections. Possible values are: 


LAT$C_DISABLED Server mode disabled (this is the 
default). 
LAT$C_ENABLED Server mode enabled. 
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Table 5-17 LAT$C_ENT_NODE Item Codes (Continued) 


Item Code 


Meaning 


LAT$_ ITM _SERVICE_RESPONDER 
(LOCAL) 


LAT$_ITM_OUTGOING_SES_LIMIT 
(LOCAL) 


LAT$_ITM_INCOMING_SES_LIMIT 
(LOCAL) 


LAT$_ITM_USER_GROUPS (LOCAL) 


LAT$_ITM_CIRCUIT_TIMER (BOTH) 


LAT$_ITM_CPU_RATING (LOCAL) 


LAT$_ ITM _KEEPALIVE_TIMER 
(LOCAL) 


LAT$_ITM_ MULTICAST TIMER 
(BOTH) 


LAT$_ITM_CONNECTIONS (BOTH) 


LAT$C_ITM_LARGE_BUFFERS 


LAT$C_ITM_ 
ANNOUNCEMENTS 


Indicates whether the node is to respond to service inquiries 
originating from a remote system. These inquiries are not 
necessarily directed at services being offered by the node. Refer to 
the HP OpenVMS System Management Utilities Reference 
Manual for more information on this feature. Possible values are: 


LAT$C_DISABLED Service responder disabled (this is 
the default). 
LAT$C_ENABLED Service responder enabled. 


Maximum number of outgoing LAT sessions. A value of 0, which 
is the default, indicates that the limit is determined by system 
resources. 


Maximum number of interactive LAT sessions. A value of 0, 
which is the default, indicates that the limit is determined by 
system resources. 


Bit mask of LAT group codes to be used when attempting 
outbound connections using the MASTER side of the LAT 
protocol. 


Circuit timer value in milliseconds. Possible values are 10 to 1000 
milliseconds. The default is 80 milliseconds. 


CPU rating. 


Keepalive timer value in seconds. Possible values are 10 to 255 
seconds. The default is 20 seconds. 


Multicast timer value in seconds. Possible values are 10 to 180 
seconds. The default is 20 seconds. 


Indicates whether inbound connections (interactive sessions) can 
be accepted. Possible values are: 


LAT$C_DISABLED Inbound connections disabled. 


LAT$C_ENABLED Inbound connections enabled (this 
is the default). 


Indicates in Boolean logic whether the LAT software is using 
large packet support by default. 


Indicates in Boolean logic whether the LAT software is 
transmitting LAT service advertisement messages. 
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Node service information is presented as a list of node service subblocks, with each subblock containing 
information about one particular service offered by the node. The subblock item code 
LAT$_ITM_NODE_SVC_BLOCK has the LAT$V_STRING bit set to 1, and the string length byte actually 
contains the length of the entire subblock. Each subblock itself is an itemlist and consists of the item codes 
listed in Table 5-18. 


Table 5-18 Node Service Subblock Item Codes 
Item Code Meaning 
LAT$_ITM_SERVICE_NAME Name of a LAT service offered by the node. 
(BOTH) 
LAT$ ITM SERVICE_STATUS Status of the service. Possible values are: 
(BOTH) 
LAT$C_AVAILABLE Service available. 
LAT$C_UNAVAILABLE Service unavailable. 
LAT$_ITM_SERVICE_TYPE Type of service. Possible values are: 
(LOCAL) 
LAT$C_ST_GENERAL Creates a general timesharing service. 


LAT$C_ST_APPLICATION Creates a special application service 
that must then be associated with ports 
dedicated to accepting connections to 
this service (dedicated ports). 


LAT$_ITM_RATING (BOTH) LAT service rating associated with the service. 


LAT$_ITM_RATING_TYPE Type of LAT rating calculation being done by this node. Possible values 
(LOCAL) are: 
LAT$C_STATIC Static rating calculation 
LAT$C_DYNAMIC Dynamic rating calculation 


LAT$_ITM_IDENTIFICATION Identification string associated with the service. 
(BOTH) 


On Alpha and I64 systems, port counters information is presented as a counters subblock. The subblock item 
code LAT$_ITM_COUNTERS has the LAT$V_STRING bit set to 1, and the string length byte actually 
contains the length of the entire subblock. The subblock itself is an itemlist and consists of the item codes 
listed in Table 5-19. 


Table 5-19 Node Counters Item Codes 
Item Codes Meaning 
LAT$_ITM_CTPRT_LCL Indicates number of local accesses to port. 
LAT$_ITM_CTPRT_SLCA Indicates number of solicitations accepted. 
LAT$_ITM_CTPRT_SLCR Indicates number of solicitations rejected. 
LAT$_ITM_CTPRT_ISOLA Indicates number of incoming solicitations accepted. 


232 


Table 5-19 


Terminal Driver 
Terminal Function Codes 


Node Counters Item Codes (Continued) 


Item Codes 


Meaning 


LAT$_ITM_CTPRT_ISOLR 
LAT$_ITM_CTPRT_FRAMERR 


LAT$_ITM_CTPRT_PARERR 


LAT$_ITM_CTPRT_OVERRUN 


LAT$_ITM_PASSWORD_FAILURES 


Indicates number of incoming solicitations rejected. 


Indicates number of framing errors for named port. 
Returned in port counter subblock. 


Indicates number of parity errors for named port. Returned 
in port counter subblock. 


Indicates number of data overruns for named port. 
Returned in port counter subblock. 


Indicates password failures. 


Node counters information is presented as a counters subblock. The subblock item code 
LAT$_ITM_COUNTERS has the LAT$V_STRING bit set to 1, and the string length byte actually contains 
the length of the entire subblock. The subblock itself is an itemlist and consists of the item codes listed in 


Table 5-20. 
Table 5-20 


Node Counters Item Codes 


Item Codes 


Meaning 


LAT$_ITM_CTNOD_SSZ (BOTH) 
LAT$_ITM_CTNOD_MSGR (BOTH) 
LAT$_ITM_CTNOD_MSGT (BOTH) 
LAT$_ITM_CTNOD_SLTR (BOTH) 
LAT$_ITM_CTNOD_SLTT (BOTH) 
LAT$_ITM_CTNOD_BYTR (BOTH) 
LAT$_ITM_CTNOD_MNA (BOTH) 
LAT$_ITM_CTNOD_DUP (BOTH) 
LAT$_ITM_CTNOD_MRT (BOTH) 
LAT$_ITM_CTNOD_ILM (BOTH) 
LAT$_ITM_CTNOD_ILS (BOTH) 
LAT$_ITM_CTNOD_SLCA (BOTH) 
LAT$_ITM_CTNOD_SLCR (BOTH) 
LAT$_ITM_CTNOD_TER (LOCAL) 
LAT$_ITM_CTNOD_RES (LOCAL) 
LAT$_ITM_CTNOD_NTB (LOCAL) 
LAT$_ITM_CTNOD_TMO (LOCAL) 


Seconds since zeroed 
Messages received 
Messages transmitted 
Slots received 

Slots transmitted 

Bytes received 

Multiple node addresses 
Duplicates received 
Messages retransmitted 
Illegal messages received 
Illegal slots received 
Solicitations accepted 
Solicitations rejected 
Transmit errors 
Resource errors 

No transmit buffer 


Virtual circuit timeout 
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Table 5-20 Node Counters Item Codes (Continued) 
Item Codes Meaning 
LAT$_ITM_CTNOD_DOB (LOCAL) Discarded output bytes 
LAT$_ITM_CTNOD_LSTER (LOCAL) Last transmit error 


LAT$_ITM_CTNOD_MCBXMT (LOCAL) Number of multicast bytes transmitted 
LAT$_ITM_CTNOD_MCBRCV (LOCAL) Number of multicast bytes received 
LAT$_ITM_CTNOD_MCMXMT (LOCAL) Number of multicast messages transmitted 
LAT$ ITM CTNOD_MCMRCV (LOCAL) Number of multicast messages received 
LAT$_ITM_CTNOD_SOLFAIL (LOCAL) Number of solicitation failures 


LAT$_ITM_CTNOD_ATLOS (LOCAL) Number of times attention slot data was lost 
LAT$_ITM_CTNOD_DATLOS (LOCAL) Number of times user data was lost 
LAT$_ITM_CTNOD_NOREJ (LOCAL) Number of times a reject slot could not be sent 
LAT$_ITM_CTNOD_LOSCT (LOCAL) Number of times remote node counters were lost 


LAT$_ITM_CTNOD_LOSSAM (LOCAL) Number of service announcement messages lost 


LAT$_ITM_CTNOD_NOSAM (LOCAL) Number of times a service announcement message could 
not be sent 

LAT$_ITM_CTNOD_NOSTS (LOCAL) Number of times node status was lost 

LAT$_ITM_CTNOD_NOXMT (LOCAL) Number of times no link was available for a transmit 


LAT$ ITM CTNOD_CTLERR (LOCAL) Number of controller errors 
LAT$ ITM CTNOD_CERRCOD (LOCAL) Lost controller error 


LAT$_ITM_CTNOD_ISOLA (LOCAL) Number of incoming solicitations accepted 
LAT$_ITM_CTNOD_ISOLR (LOCAL) Number of incoming solicitations rejected 
LAT$_ITM_CTNOD_PROTO (LOCAL) Protocol error count 

LAT$ ITM CTNOD_XSTR (REMOTE)! Indicates that the node attempted to start up too many LAT 


sessions for a specific virtual circuit 


1. Alpha and 164 specific. 


Several protocol errors are also included in a separate subblock. The protocol errors item code is 
LAT$ ITM PROTOCOL_ERRORS and has LAT$V_STRING set (the size of the subblock is contained in the 
first byte following the item code). The item codes and the events they represent are listed in Table 5-21. 


Table 5-21 Protocol Error Item Codes 


Item Codes Meaning 


LAT$_ITM_CTPRO_IVM (LOCAL) Invalid message type received. 
LAT$_ITM_CTPRO_ISM (LOCAL) Invalid start message received. 
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Protocol Error Item Codes (Continued) 


Item Codes 


Meaning 


LAT$_ITM_CTPRO_IVS (LOCAL) 
LAT$_ITM_CTPRO_NIZ (LOCAL) 
LAT$_ITM_CTPRO_ICI (LOCAL) 
LAT$_ITM_CTPRO_CSI (LOCAL) 
LAT$_ITM_CTPRO_NLV (LOCAL) 
LAT$_ITM_CTPRO_HALT (LOCAL) 
LAT$_ITM_CTPRO_MIZ (LOCAL) 
LAT$_ITM_CTPRO_SIZ (LOCAL) 


LAT$_ITM_CTPRO_CRED 
(LOCAL) 


LAT$_ITM_CTPRO_RCSM 
(LOCAL) 


LAT$_ITM_CTPRO_RDSM 
(LOCAL) 


LAT$_ITM_CTPRO_INVCLASS 
(LOCAL) 


LAT$ ITM_CTPRO_EXCSTART 
(LOCAL)! 


Invalid sequence number received. 
Zero-node index received. 

Node circuit index out of range. 
Node circuit sequence invalid. 
Node circuit index no longer valid. 
Circuit was forced to halt. 

Invalid master slot index. 

Invalid slave slot index. 


Invalid credit field. 


Repeat creation of slot by master. 


Repeat disconnection of slot by master. 


Indicates the number of times a LAT message was received with 
an invalid service class specified in that message (local node only). 


Indicates that a remote node attempted to start up too many LAT 
sessions. When a virtual circuit is started between two LAT nodes, 
the maximum number of sessions on that virtual circuit is 
negotiated. If the master node attempts to create more sessions 
than the maximum number of sessions on a virtual circuit, then 
the operating system rejects the excess connections and 
increments this counter. 


1. Alpha and 164 specific. 


Table 5-22 lists the item codes that are returned for the LAT$C_ENT_SERVICE entity type. As in Table 5-17, 
item codes noted as LOCAL are returned only if the information being returned is for a locally offered service. 
Item codes noted as REMOTE are returned only if the information being returned is for a service offered by a 
remote node. Item codes noted as BOTH are returned for both types of services. 


Table 5-22 


LAT$C_ENT_ SERVICE Item Codes 


Item Code 


Meaning 


LAT$_ITM_SERVICE_NAME 
(BOTH, SUMMARY) 


Service name. 


LAT$_ITM_SERVICE_STATUS _ Status of the specified service. Possible values are: 


(BOTH, SUMMARY) 


LAT$C_AVAILABLE 


Service available. 
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Table 5-22 LAT$C_ENT_SERVICE Item Codes (Continued) 


Item Code 


Meaning 


LAT$_ITM_SERVICE_TYPE 
(LOCAL,SUMMARY) 


LAT$_ITM_ IDENTIFICATION 
(BOTH, SUMMARY) 


LAT$C_UNAVAILABLE 


Type of service. Possible 
values are: 


LAT$C_ST_GENERAL 
LAT$C_ST_APPLICATION 


Service unavailable. 


General timesharing service. 


Special application service associated 
with ports dedicated to accepting 
connections to this service. 


Service identification string, as advertised by the highest rated node 
that currently offers the service. 


Service node information is presented as a list of service node subblocks, with each subblock containing 
information about one particular node that offers the service. The subblock item code 
LAT$_ITM_SVC_NODE_BLOCK has the LAT$V_STRING bit set to 1, and the string length byte actually 
contains the length of the entire subblock. Each subblock itself is an itemlist and consists of the item codes 


listed in Table 5-23. 


Table 5-23 Service Node Subblock Item Codes 


Item Code 


Meaning 


LAT$C_ITM_NODE_ NAME 
(BOTH) 


LAT$_ITM_STATE (LOCAL) 


LAT$_ITM_NODE_STATUS 
(REMOTE) 
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Name of a LAT node that offers the selected service. 


Current state of the LAT protocol on the local node. Possible values 


are: 


LAT$C_ON 


LAT$C_OFF 


LAT$C_SHUT 


New connections are allowed, and the 
LAT protocol is running. 


New connections are not allowed, and 
any current connections are 
abnormally terminated. The LAT 
protocol is not running. 


No new connections are allowed. 
Currently active connections are still 
maintained. The LAT protocol remains 
running only until the last active 
sessions is disconnected, at which time 
the node is placed in the OFF state. 


Current status of the remote node. This item code is present only ifa 
LAT virtual circuit does not currently exist to the remote node. 


Possible values are: 


LAT$C_REACHABLE 


Remote node is reachable. 


LAT$C_UNREACHABLE Remote node is unreachable. 
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Table 5-23 Service Node Subblock Item Codes (Continued) 
Item Code Meaning 
LAT$C_UNKNOWN Remote node status is unknown. 


LAT$_ITM_CONNECTED_COUNT 
(REMOTE) 


LAT$_ITM_RATING (BOTH) 


LAT$_ITM_RATING_TYPE 
(LOCAL) 


LAT$_ITM_ IDENTIFICATION 
(BOTH) 


Number of LAT sessions from the local node to this remote node. 
This item code replaces the LAT$_ITM_NODE_STATUS item code 
for remote nodes to which a LAT virtual circuit currently exists. 


LAT service rating associated with the service. 


Type of LAT rating calculation being done by this node. Possible 
values are LAT$C_STATIC and LAT$C_DYNAMIC. 


Identification string associated with the service. 


Service counters information is presented as a counters subblock. The subblock item code 
LAT$_ITM_COUNTERS has the LAT$V_STRING bit set, and the string length byte actually contains the 
length of the entire subblock. Each subblock itself is an itemlist and consists of the item codes listed 


inTable 5-24 Table 5-24. 


Table 5-24 Service Counters Subblock Item Codes 


Item Codes 


Meaning 


LAT$_ITM_CTSRV_SSZ (BOTH) 


LAT$_ITM_CTSRV_MCNA 
(BOTH) 


LAT$_ITM_CTSRV_MCNC 
(BOTH) 


LAT$_ITM_CTSRV_SCNA 
(BOTH) 


LAT$_ITM_CTSRV_SCNR 
(BOTH) 


LAT$_ITM_DED_PORT_ BLOCK 
(LOCAL) 


LAT$_ITM_PASSWORD_ 
FAILURE 


Seconds since zeroed. 


Outgoing connections attempted (the number of times the local node 
has attempted to connect to the service offered on a remote node). 


Outgoing connections completed (the number of times the local node 
successfully connected to the service offered on a remote node). 


Incoming connections accepted (the number of times the local node has 
accepted a connection request from a remote node to the locally offered 
service). 


Incoming connections rejected (the number of times the local node 
rejected a connection request from a remote node to the locally offered 
service). 


If the selected service is an application service offered by the local node, 
a list of one or more port subblocks is included in the itemlist. These 
subblocks describe the dedicated port or ports associated with this 
application service, with each subblock describing one particular port. 
The subblock item code LAT$_ITM DED _PORT_BLOCK has the 
LAT$V_STRING bit set, and the string length byte actually contains 
the length of the entire subblock. Each subblock itself is an itemlist and 
currently consists only of the following item code: 


LAT$_ITM_PORT_ Name of the dedicated port. 
NAME (LOCAL) 


Indicates password failures. 


237 


Terminal Driver 
Terminal Function Codes 


Table 5-25 lists the item codes that are returned for the LAT$C_ENT_LINK entity type. 


Table 5-25 LAT$C_ENT_LINK Item Codes 
Item Codes Meaning 
LAT$ ITM LINK NAME Link name (such as LAT$LINK). 
(SUMMARY) 


LAT$_ITM STATE (SUMMARY) State of the link. Possible values are: 


LAT$C_ON New connections are allowed, and the LAT 
protocol is running. 


LAT$C_OFF New connections are not allowed, and any 
current connections are abnormally 
terminated. The LAT protocol is not running. 


LAT$C_SHUT No new connections are allowed. Currently 
active connections are still maintained. The 
LAT protocol remains running only until the 
last active session is disconnected, at which 
time the node is placed in the OFF state. 


LAT$_ITM_DEVICE_NAME The name of the LAN device used for the link. 
(SUMMARY) 


LAT$_ITM_DATALINK_ADDRESS The LAN device's current physical address for the link. 


LAT$_ITM_DECNET_ADDRESS Indicates whether the link attempts to use the default DECnet LAN 
address when starting the data link controller (enabling the LAT 
protocol). Possible values are: 


LAT$C_DISABLED DECnet LAN address use disabled. 


LAT$C_ENABLED DECnet LAN address use enabled (this is the 
default. 


Link counters information is presented as a counters subblock. The subblock item code 
LAT$_ITM_COUNTERS has the LAT$V_STRING bit set, and the string length byte actually contains the 
length of the entire subblock. Because the link counters are independent of the protocol type, they include not 
only LAT messages and events, but also all other protocol messages and events (that is, DECnet) associated 
with the same LAN device. The counters are actually maintained by the LAN device driver and are identified 
within the subblock by the nonprotocol-specific item codes listed in Table 5-26. 


Table 5-26 Link Counters Item Codes 
Item Codes Meaning 
NMA$C_CTLIN_ZER Seconds since zeroed 
NMA$C_CTLIN_DBR Messages received 
NMA$C_CTLIN_DBS Messages transmitted 
NMA$C_CTLIN_MBL Multicast messages received 
NMA$C_CTLIN_MBS Multicast messages transmitted 


238 


Terminal Driver 
Terminal Function Codes 


Table 5-26 Link Counters Item Codes (Continued) 


Item Codes 


Meaning 


NMA$C_CTLIN_BRC 
NMA$C_CTLIN_BSN 
NMA$C_CTLIN_MBY 
NMA$C_CTLIN_MSN 
NMA$C_CTLIN_RFL 
NMA$C_CTLIN_SFL 
NMA$C_CTLIN_OVR 
NMA$C_CTLIN_UBU 
NMA$C_CTLIN_SBU 
NMA$C_CTLIN_LBE 
NMA$C_CTLIN_BS1 
NMA$C_CTLIN_BSM 
NMA$C_CTLIN_BID 
NMA$C_CTLIN_CDC 


Bytes received 

Bytes transmitted 

Multicast bytes received 
Multicast bytes transmitted 
Receive errors 

Transmit errors 

Data overrun 

User buffer unavailable 

System buffer unavailable 

Local buffer errors 

Messages sent, single collisions 
Messages sent, multiple collisions 
Messages sent, initially deferred 


Transmit collision detection check failure 


Table 5-27 lists additional link counter item codes of the LINK entity. 
Table 5-27 Additional Link Counters Item Codes 


Item Codes 


Meaning 


LAT$_ITM_CTLAT_RMSG 
LAT$_ITM_ CTLAT_RBYT 
LAT$_ITM_CTLAT_ XMSG 
LAT$_ITM_CTLAT XBYT 
LAT$_ITM_CTLAT_MUL_RMSG 
LAT$_ITM_CTLAT_MUL_RBYT 
LAT$_ITM_CTLAT_MUL_XMSG 
LAT$_ITM_CTLAT MUL_XBYT 
LAT$_ITM_ LAT _DEV_CTR_BLOCK 


Count of LAT messages received through link 

Count of bytes for LAT received through link 

Count of LAT messages transmitted through link 

Count of bytes for LAT transmitted through link 

Count of LAT multicast messages received through link 
Count of multicast bytes for LAT received through link 
Count of LAT multicast messages transmitted through link 
Count of multicast bytes for LAT transmitted through link 


This block contains the LAT-specific counters for the 
specified link. Counters returned in this block are the ones 
defined above (with CTLAT in their name). These counters 
are LAT-specific for the link (device). They do not include 
counts from other protocols using the same adapter. 
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The counter item codes listed in Table 5-27 are used by LATCP in the display generated by the command: 


S SHOW LINK /COUNTER 


The display looks similiar to the following: 


LATSLINK 
_XQAI1: 


Link Name: 
Device Name: 


Seconds Since Zeroed: 
Messages Received: 

LAT Messages Received: 
Multicast Msgs Received: 

LAT Multicast Msgs Received: 
Bytes Received: 

LAT Bytes Received: 

Multicast Bytes Received: 

LAT Multicast Bytes Received: 
System Buffer Unavailable: 
Unrecognized Destination: 
Receive 


Errors: 


(bitmask = 
Error: 


Receive Errors 
Block Check 
Framing Error: 
Frame Too Long: 
Frame Status 
Frame Length 


001) 


Error: 


Error: 


CSMACD Specific Counters 


Transmit CDC Failure: 


Messages Transmitted - 
Single Collision: 
Multiple Collisions: 
Initially Deferred: 


65535 
7080630 
1484817 
5578139 
5093417 

678189475 
107809441 
602984574 
565264261 
1638401 
65537 

7 


Messages Sent: 2135394 
LAT Messages Sent: 2086167 
Multicast Msgs Sent: 10775 
LAT Multicast Msgs Sent: 9142 
Bytes Sent: 1312778402 
LAT Bytes Sent: 1278118808 
Multicast Bytes Sent: 1696264 
LAT Multicast Bytes Sent: 1448342 
User Buffer Unavailable: 1 
Data Overrun: 1 
Transmit Errors: 1 
Transmit Errors (bitmask = 001) - 
Excessive Collisions: Yes 
Carrier Check Failure: No 
Short Circuit: No 
Open Circuit: No 
Frame Too Long: No 
Remote Failure To Defer: No 
Transmit Underrun: No 
Transmit Failure: No 


Table 5-28 lists the item codes that are returned for the LAT$C_ENT_PORT entity type. 


Table 5-28 


LAT$C_ENT_ PORT Item Codes 


Item Code 


Meaning 


LAT$_ITM_PORT_NAME SUMMARY 


LAT$_ITM_PORT_TYPE_SUMMARY 


Possible values are: 
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Table 5-28 LAT$C_ENT_PORT Item Codes (Continued) 


Item Code 


Meaning 


LAT$_PT_FORWARD 
LAT$_PT_INTERACTIVE 


LAT$_PT_APPLICATION 
LAT$_PT_DEDICATED 
LAT$_ ITM _QUEUED 


Possible values are: 

LAT$C_DISABLED 

LAT$C_ENABLED 
LAT$_ITM_SERVICE_CLASS 


Possible values are: 

LAT$C_SERVCLASS_INTERACTIVE 

LAT$C_SERVCLASS_TESTSERVICE 

LAT$C_SERVCLASS_XTRANSPORT 

LAT$C_SERVCLASS_FONT 
LAT$_ITM_ DISPLAY NUMBER 


LAT$_ITM_DISCONNECT_REASON 


LAT$C_PT_STATE DISCONNECTING! 


LAT$_ITM_CONNECTED_NODE_NAME! 


Forward port used for outgoing LAT connections or for 
management functions. 


Interactive port created as the result of an incoming 
LAT connection request. 


Application port for solicited connections. 
Dedicated port associated with a local service. 


Controls whether the solicited connection requests 
queued or nonqueued access. 


Queued access disabled. 
Queued access enabled (this is the default). 


Indicates the class driver with which the device is 
communicating. This item code can be used only with 
an entity status of LAT$C_ENTS_NEW. Therefore, the 
service class must be specified when the device is 
created. An attempt to change the service class of an 
existing device returns SS$_BADPARAM. 


Service class 1, TTDRIVER (this is the default). 
Service class 2, TEST SERVICE. 

Service class 3, X Protocol. 

Service class 4, X fonts. 


Display number value for the device. This field has 
meaning for services classes 3 and 4 (X) only. It returns 
a value of 0 for all other service classes. 


Reason (if any) for the last disconnect on the port. If it 
is not a 0--19 LAT rejection code, it is a LAT message 
code. The 0--19 LAT rejection code meanings are listed 
in Table 5-32. 


Name of service to which this port is connected. For 
forward and application ports, this is the name of the 
remote service to which the port is connected (if any). 
For interactive and dedicated ports, this is the name of 
the local service that accepted the remote-initiated 
connection. 


Name of remote node to which this port is connected. 
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Table 5-28 LAT$C_ENT_ PORT Item Codes (Continued) 


Item Code 


Meaning 


LAT$_ITM_CONNECTED_PORT_NAME! 
LAT$_ITM_CONNECTED_LINK_NAME! 


LAT$_ITM_TARGET_SERVICE_NAME? 


LAT$_ITM_TARGET_NODE_NAME? 
LAT$_ITM_TARGET_PORT_NAME? 
LAT$_ITM_NODE_QUEUE_POSITION® 


LAT$_ITM_SERVICE_QUEUE_POSITION® 


LAT$_ITM_PORT_STATE 
Possible values are: 
LAT$C_PT_STATE_INACTIVE 
LAT$C_PT_STATE_CONNECTING 
LAT$C_PT_STATE_ACTIVE 
LAT$C_PT_STATE_DISCONNECTING 


Name of remote port to which this port is connected. 
Name of the link on which the LAT connection exists. 


Target service name for connection of forward or 
application ports. For dedicated ports, this item code 
specifies the local service with which the port is 
associated. 


Target node name for connection of forward or 
application ports. 


Target port name for connection of forward or 
application ports. 


Indicates current node queue position for connect 
request. Returned during SENSEMODE of port entity. 


Indicates current service queue position for connect 
request. Returned during SENSEMODE of port entity. 


Current port state. 


Port is inactive. 
Port connection in progress but not complete. 
Port has active LAT connection. 


Port LAT connection in process of terminating. 


1. Returned only when the LTA port has an active LAT connection. 
2. Shows information about how the port is set up. May be returned even if there is no current LAT 


connection. 
3. Alpha and 164 specific. 


On Alpha and 164 systems, the item codes for queue entries are listed in Table 5-29. 


Table 5-29 LAT SENSEMODE Queue Entries 
Item Code Meaning 
LAT$_ITM_QUEUED_ENTRY_ID Indicates by string the queue entry ID name. 
(SUMMARY) 
LAT$_ITM_NODE_QUEUE_POSITION Indicates the current position of entry in node wide queue. 
(SUMMARY) 


LAT$_ITM_SERVICE_QUEUE_POSITION Indicates the current position of entry in service wide 
(SUMMARY) queue. 
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Table 5-29 LAT SENSEMODE Queue Entries (Continued) 
Item Code Meaning 
LAT$_ITM_NODE_NAME (SUMMARY) Indicates where the remote node name queue entry came 
from. 


LAT$_ITM_SERVICE_NAME (SUMMARY) _ Indicates the target service name to which the queue entry 


is queued (if specified). 


LAT$_ITM_PORT_NAME (SUMMARY) Indicates the target port name to which the entry is queued 
(if specified). 

LAT$_ITM_LINK_NAME Returns the link name on which the queued request is 
active. 

LAT$_ITM_DATALINK_ADDRESS Returns the remote node that issued the request’s data link 
address. 


5.4.4.5 Programming Application Ports 


An application port is used to connect to a remote device (typically a printer) on a terminal server or to a 
dedicated port on another LAT service node. The LAT port driver can only connect to a remote device if the 
device is currently not in use. Table 5-30 lists the conditions that can occur when an application program 
issues an IO$M_LT_CONNECT request for a connection to a remote device. After a request is queued on the 
terminal server (or dedicated port on another LAT service node), the QIO request is not completed until the 


connection is established, rejected, or times out. 


Table 5-30 IO$M_LT_CONNECT Request Status 
Event IOSB Status Explanation 

Connection established SS$ NORMAL The connection is successful, and the port 
is ready for use. 

Connection timeout SS$_TIMEOUT The connection did not complete because 
communication was never established with 
the remote end. IOSB+2 contains 
LAT$_CONTIMEOUT. 

Connection rejected SS$_ ABORT. IOSB+2 The connection cannot be made. The LAT 

contains LAT rejection port driver updates the I/O status block. 
code or LAT facility The LAT rejection codes (0--19) are listed 


message code. 


Connection request SS$_ILLIOFUNC 


Connection already established SS$_DEVACTIVE 
on port 


in Table 5-32. 


The QIO request is not to an application, 
dedicated, or forward port. The LAT port 
driver rejects the request immediately. 


The QIO request is for a port already in 
use. The LAT port driver rejects the 
request immediately. 
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Table 5-30 IO$M_LT_CONNECT Request Status (Continued) 
Event IOSB Status Explanation 
Incorrectly configured LAT SS$_DEVREQERR The LAT port is incorrectly configured. 
port This may mean that the port type was 


neither forward nor application nor 
dedicated, because a forward port had no 
service name mapped or because an 
application port had no node name 
mapped. 


Insufficient resources SS$_INSFMEM The QIO request failed because the LAT 
port driver could not get system memory to 
complete the connection. 


Before the application port can be used, it must be mapped to a remote node name, and either the port name 
or the service name of the remote terminal server port. (These names must be defined locally on the terminal 
server.) The application port is mapped with the IO$M_LT_SETMODE modifier, specifying the following 
items in the P1 itemlist parameter: 


e LAT$ ITM _TARGET_NODE_NAME—The node name. The node name is the name of the terminal server 
where the application device is located. 


e LAT$ ITM_TARGET_PORT_NAME—The port name. 
e LAT$ ITM _TARGET_SERVICE_NAME—The service name. 


The queued status of the connection can also be mapped to the port by specifying the LAT$_ITM_QUEUED 
item in the P1 itemlist parameter. Valid values for this item are: 


e LAT$C_ENABLED—Port has queued status. This is the default. 
e LAT$C_DISABLED—The port does not have queued status. 


5.4.4.6 Programming Application Services and Dedicated Ports 


Rather than the normal timesharing service offered by the operating system, application programs can make 
use of LAT application services that allow terminal server users (or users on sytems with outgoing 
connections) to connect to a specialized application. To do this, the system manager must create LAT ports 
that are dedicated to a particular application service. (Alternatively, this LAT port creation can be done from 
a program using the QIOs discussed in previous sections, providing OPER privilege.) When the remote user 
makes the connection to the application service, the connection is directly to the application program that 
controls a LAT port (LTA device) associated with the service. In this case the prompt, Username:, is not 
received. HP recommends that you follow these steps to create an application service: 


1. Define the dedicated ports in LAT$SYSTARTUP.COM and execute the command procedure in 
SYSTARTUP_VMS.COM. (Refer to the HP OpenVMS System Management Utilities Reference Manual 
and the HP OpenVMS System Manager’s Manual for additional information. ) 


2. Run the application program. Within the application program, allocate dedicated ports with the same 
name as those defined in LAT$SYSTARTUP.COM. Use the Assign I/O Channel ($ASSIGN) system 
service to assign service channels to the ports. 


3. Post a read request to the dedicated ports. When the terminal user connects to the service and presses the 
Return key, the application program can perform I/O to the dedicated port. 
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4. To break the connection, use the Deassign I/O Channel ($DASSGN) system service to deassign the 
channel and the Deallocate Device ($DALLOC) system service to deallocate the device. The application 
program must reallocate the port and reassign the channel in preparation for the next connection. 


An example of the application service concept is a program that provides the time of day. For this example, 
the system manager includes the following lines in LAT$SYSTARTUP.COM (or enters them manually in the 
LATCP program): 


CREATE SERVICE TIME/ID="At the tone, the time will be"/APPLICATION 
CREATE PORT LTA99:/DEDICATED 
SET PORT LTA99:/SERVICE=TIME 


An application program then assigns a channel to device LTA99. When a terminal server user types 
CONNECT TIME, the user is connected to this application program, and the program prints out the time of 
day. The program then deassigns the channel, which disconnects the server user. 


A system manager may associate more than one LAT port with the same service. In that case, the application 
program that offers the service should assign channels to all of the LTA devices created for that service. 


5.4.4.7 Programming Forward Ports 


An outbound LAT connection to a remote service node can be made using a forward port. The LAT port driver 
can connect to a remote service node only if outgoing connections are enabled on the local node. Outgoing 
connections can be enabled with LATCP or with a LAT SETMODE QIO to the local node. In addition, user 
group codes on the local node must match the service group codes of the service to which they are being 
connected. LATCP can list the services to which the local node can connect. (Refer to the HP OpenVMS 
System Management Utilities Reference Manual for additional information.) Before the forward port can be 
used to make an outbound LAT connection, it must be mapped to a service and optionally, a node and port. 
The forward port is mapped with the IO$M_LT_SETMODE modifier, specifying the following items in the P1 
item list parameter: 


e LAT$ ITM TARGET SERVICE _NAME—The service name. The service name is the name of the service 
to which to connect. 


e LAT$ ITM_TARGET_NODE_NAME—The node name. The node name is the name of a specific service 
node offering the service. 


e LAT$ ITM_TARGET_PORT_NAME—The port name. The port name is the name of a specific port on the 
target node. The LAT$_ITM_TARGET_NODE_NAME item must be supplied when supplying this item. 


e LAT$ ITM_SERVICE_PASSWORD—The password. The password is required for access to a 
password-protected service. 


A LAT SETMODE QIO on a forward port does not require OPER privilege if the port name is not specified in 
the P4 parameter. In other words, the LAT SETMODE QIO must be to the port corresponding to the CHAN 
parameter (the forward port attained by assigning a channel to _LTAO:). Note that SS$_NOPRIV is returned 
if you attempt to change the port type by specifying the LAT$_ITM_PORT_TYPE item code in the P1 itemlist 
parameter. If the P4 parameter is specified, the LAT port driver also returns SS$_NOPRIV. 


Table 5-30 lists the conditions that can occur when an application program issues an IO$M_LT_CONNECT 
request for a connection to a remote service node. The QIO request is completed when a session is established 
with the service node. Once the connection completes, data can be read and written to the port with the QIO 
read and write functions. 


5.4.4.8 Queue Change Notification 


On Alpha and I64 systems, the IO$M_LT_QUE_CHG_NOTIF function modifier for $QIO allows a process to 
enable an attention asynchronous system trap (AST), which is used with the LAT $QIO connect request. The 
IO$M_LT_QUE_CHG_NOTIF function is available only for APPLICATION and FORWARD LAT devices. 
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If a $QIO connect request has been issued to a remote node and that request has been queued, this attention 
AST will be set each time the queue position changes. This AST can be used as long as the $QIO connect 
request is queued. Like a Ctrl/Y AST, it is set only once; it must be reenabled after each completion. 


If the LAT $QIO connect succeeds or if a LAT connection exists for the intended service, the AST completes 
with the SS$_ DEVACTIVE status code. 


If the LAT device does not have the queued characteristic, issuing the IO$M_LT_QUE_CHG_NOTIF function 
results in the return of SS$¢_DEVREQERR status code. 


The implementation of IO$M_LT_QUE_CHG_NOTIF is shown in the following C example: 


status - sysSqiow ( 

0, /* efn * / 
ltchannel, /* channel */ 
IO$_TTY_PORT | I0SM LT_QUE_CHG_NOTIF, 

/* function */ 
q_iosb, /* iosb */ 
0, /* astadr */ 
0, /* astprm */] 
queue_pos_change, /* Pl = ast routine Ff 
0, O, 0, 0, 0); /* P2 through P6 not used */ 


When a queue position change occurs, the AST routine is called with a 32-bit value. If this value is 0, then the 
LAT connect $QIO is about to complete, if it has not already. If the value is not 0, the lower word of 16 bits 
indicates the service queue position, and the upper word of 16 bits indicates the node queue position. 


5.4.4.9 Hangup Notification 


To allow notification by the terminal driver of abnormal termination during I/O operations, enable a Ctrl/Y 
AST on the channel. This ensures that the terminal driver notifies application programs of an abnormal 
connection termination. Note that the operating system does not return an AST parameter to the Ctrl/Y AST 
routine. 


When an application with a pending read or write request has an abnormal LAT connection completion, the 
terminal driver returns a SS$_ HANGUP status in the first word of the IOSB. The reason for the abnormal 
LAT connection completion can be attained with a LAT SENSEMODE QIO request to the port. Search the 
resulting P1 itemlist for the value corresponding to the LAT$_ITM_DISCONNECT_REASON item code. The 
value is either a LAT reject code or a LAT facility message. The LAT$V_SENSE_FULL bit must be set in the 
P3 parameter in order to receive this information. 


If IOSB indicates an abnormal completion (SS$_ABORT, see Table 5-30) on a IO$M_LT_CONNECT modifier 
QIO, the LAT port driver returns the reason for the abnormal completion in IOSB+2. The reason can also be 
attained with the LAT SENSEMODE QIO function. 


5.4.5 Sense Mode and Sense Characteristics 


The sense mode and sense characteristics functions sense the characteristics of the terminal and return them 
to the caller in the I/O status block. The following function codes are provided: 


e IO$_SENSEMODE 
e IO$_SENSECHAR 
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I0$_SENSEMODE returns the temporary characteristics of the terminal (the characteristics associated with 
the current process), and IO$_SENSECHAR returns the permanent characteristics of the terminal. 
I0$_SENSEMODE is a logical I/O function and requires no privilege. IO$_SENSECHAR is a physical I/O 
function and requires the privilege necessary to perform physical I/O. 


These function codes take the following device- or function-dependent arguments: 


e P1—Address of a characteristics buffer 
e P2—Length of characteristics buffer (default length is 8 bytes) 
For remote terminals, specify a P2 value of 8 or 12 only. 


The P1 argument points to a variable-length block, as shown in Figure 5-11. 


Figure 5-11 Sense Mode Characteristics Buffer 
31 24 23 16 15 87 0 


Page Length Basic Terminal Characteristics 
Extended Terminal Characteristics 


* Page Width P2-12 


ZKO0693GE 


In the buffer, the device class is DC$_TERM, which is defined by the $DCDEF macro. The terminal type is 
defined by the $TTDEF macro, such as TT$_LA36. The maximum entry for the buffer size (page width) is 
255. Table 5-5 lists the values for terminal characteristics. Table 5-6 lists the extended terminal 
characteristics. Characteristics values are defined by the $TTDEF macro. 


The sense mode and sense characteristics functions can take the type-ahead count, read modem, and 
broadcast function modifiers described in the following sections. 
5.4.5.1 Type-ahead Count Function Modifier 


The type-ahead count function modifier returns the count of characters presently in the type-ahead buffer 
and a copy of the first character in the buffer. In this case, the P1 argument points to a characteristics buffer 
returned by IO$M_TYPEAHDCNT. Figure 5-12 shows the format of this buffer. 


Figure 5-12 Sense Mode Characteristics Buffer (type-ahead) 


31 24 23 16 15 0 


(Reserved) First Character | Number of Characters in TypeAhead Buffer 


(Reserved) 


ZK0694GE 
5.4.5.2 Read Modem Function Modifier 


The read modem function modifier allows access to controller-dependent information. The following 
combinations of function code and modifier are provided: 
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e I0$_SENSEMODE!IO$M_RD_MODEM 

e I0$_SENSECHAR!IO$M_RD_MODEM 

These function code modifier pairs take the following device- or function-dependent argument: 
e P1—The address of a quadword block 

Figure 5-13 shows the format of this block. 


Figure 5-13 Sense Mode P1 Block 


31 24 23 16 15 87 0 


P1: 


ZKO695GE 


The receive modem field returns the value of the current input modem signals. Any or all of the following 
signals can be returned: 


e TT$M_DS_DSR—Data set ready (DSR) 

e TT$M_DS_RING—Calling indicator (RING) 

e TT$M_DS_CARRIER—Data channel received line signal detector (CARRIER) 
e TT$M_DS_CTS—Ready for sending (CTS) 

e TT$M_DS_SECREC—Received backward channel data (Sec RxD) 

The $TTDEF macro defines the symbols for the receive modem field. 


The controller type field returns the type of terminal controller in use by the currently active terminal line. 
The $DCDEF macro defines the symbols for the following types of controllers: 


e DT$_DZ11—DZ11 and DZV11 
¢ DT$_DZ32—DZ32 

¢ DT$_DMF32—DMF32 

¢ DT$_DMB32—DMB32 

¢ DT$ _DMZ32—DMZ32 

e DT$ DHV—DHV11 

e DT$ DHU—DHU11 

e DT$ LAT—LAT server 


NOTE For LAT devices, the receive modem field of the IO$M_RD_ MODEM function modifier does not 
return any valid modem signal data. 


The IO$M_RD_MODEM function modifier is not supported for remote terminals. The status 
SS$_DEVREQERR is returned in the I/O status block. 
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5.4.5.3 Broadcast Function Modifier 


The broadcast function modifier returns those bits that have been set by the set mode function modifier 
IO$M_BRDCST (see Table 5-12 in Section 5.4.3.6). The following combination of function code and modifier is 
provided: 


¢ I10$_SENSEMODE!IO$M_BRDCST 
This function code modifier pair takes the following device- or function-dependent arguments: 


P1—A buffer that contains the bits that specify the requester IDs to be broadcast. (If the bit is set in the 
first longword, that particular command is turned off for broadcast.) 


P2—The length of the P1 buffer. 


5.5 I/O Status Block 


The I/O status block (IOSB) formats for the read, write, set mode, set characteristics, sense mode, sense 
characteristics, and LAT port driver I/O functions are shown in Figures Figure 5-14, Figure 5-16, Figure 5-17, 
and Figure 5-18. Figure 5-15 shows the IOSB format for the itemlist read function. Appendix A lists the 
status returns for these functions. (The OpenVMS system messages documentation provides explanations 
and suggested user actions for these returns.) 


In Figure 5-14, the offset to terminator at IOSB+2 is the count of characters before the terminator character 
(see Section 5.4.1.2). The terminator character is in the buffer at the offset specified in IOSB+2. When the 
buffer is full, the offset at IOSB+2 is equal to the requested buffer size. At the same time, IOSB+4 is equal to 
0. In the case of multiple character escape sequences that act as terminators, the terminator at IOSB+4 is the 
first character (ESC) of the escape sequence. IOSB+6 contains the size of the terminator string, usually 1. 
However, in an escape sequence, IOSB+6 contains the size of the validated escape sequence (see Section 
5.2.1.4). The sum of IOSB+2 and IOSB+6 is the number of characters in the buffer. 


Figure 5-14 IOSB Contents—Read Function 


+2 IOSB 


Terminator Size Terminator 


+6 +4 


ZKO696GE 


249 


Terminal Driver 
I/O Status Block 


In Figure 5-15 the terminator position word contains a number, the character of which is determined by the 
mode of operation. For itemlist read operations that do not specify TRM$K_EM_RDVERIFY, this word 
contains the number of characters from the end of the buffer to the cursor location at the time the terminator 
character was received. If TRM$K_EM_RDVERIFY is specified, the terminator position word contains the 
offset into the buffer from the nonverified character. 


Figure 5-15 IOSB Contents—Itemlist Read Function 


Offset to Terminator Status 


Terminator 


Cursor Position| Terminator 
from EOL Length (Reserved) Character 


IOSB Contents: Itemlist Read Function 
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The byte at IOSB+5 passes the status information, listed in Table 5-31, on TRM$K_EM_RDVERIFY 
operations in which TRM$M_TM_ARROWS or TRM$M_TM_TOGGLE is set in TRM$_MODIFIERS. 


Table 5-31 Byte IOSB+5 Status Information 
Bit Interpretation 

7 (sign bit) 0 to indicate rest of bits valid. This applies to 
insert/overstrike and arrow key read verify functionality 
only. 

6-2 Always 0 if bit 7 is equal to 0. Not used; reserved for future 
use. 

1 TRM$V_ST_OTHERWAY Set to indicate that read is terminated in left-justify insert 


mode or right-justify overstrike mode. 


0 TRM$V_ST_FIELD_FULL Read terminated on an autotab field full condition. IOSB+7 
contains an index to the cursor. 


In Figure 5-16, the remote terminal driver does not return the number of lines output or the cursor position. 


Figure 5-16 IOSB Contents—Write Function 


IOSB Contents: Write Function 
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In Figure 5-17, the TT driver attempts to return the correct data in IOSB after a SETMODE or SETCHAR. To 
be sure the returned data is correct, the user should follow the SETMODE or SETCHAR with a 
SENSEMODE or SENSECHAR. 


Figure 5-17 IOSB Contents—Set Mode, Set Characteristics, Sense Mode, and Sense 
Characteristics Functions 


Receive Speed *} Transmit Speed Status 


_ Parity Flags LF Fill Count |} CR Fill Count 


* Only specified if different than transmit speed. 
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When an application program makes an I/O request for a connection to a remote device on a terminal server, 
the LAT port driver places status information about the request into the first word of the I/O status block, as 
shown in Figure 5-18. Table 5-30 lists the possible status returns. 


If the server rejects the request, the LAT port driver returns a numeric LAT rejection code in the second word 
of the I/O status block. Table 5-32 lists the LAT rejection codes. 


Figure 5-18 IOSB Contents—LAT Port Driver Function 


+2 0 


(Reserved) (Reserved) 
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Table 5-32 LAT Rejection Codes 


Value Reason 


Reason is unknown. 

User requested disconnect. 

System shutdown in progress. 

Invalid slot received. 

Invalid service class received. 
Insufficient resources to satisfy request. 
Service in use. 

No such service. 


Service is disabled. 


oOo wa nreonu4#rk wo NYDN FF OO 


Service is not offered on the requested port. 


a" 
Oo 


Port name is unknown. 
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Table 5-32 LAT Rejection Codes (Continued) 

Value Reason 

11 Invalid password. 

12 Entry is not in queue. 

13 Immediate access rejected (server queue full). 

14 Access denied (group code mismatch). 

15 Corrupted solicit request. 

16 COMMAND_TYPE code is illegal/not supported. 

17 Start slot cannot be sent. 

18 Queue entry deleted by local node. 

19 Inconsistent or illegal request parameters. 


5.6 Terminal Driver Programming Examples 


The VAX C program LAT.C shown in Example 5-1 initiates and maintains an outbound LAT session from the 
local node. It demonstrates the following LAT $QIO functions: 


e Cloning the LAT template device (LTAO:) 
¢ IO$M_LT_SETMODE 

¢ IO$M_LT_CONNECT (on forward port) 
e IO$M_LT_SENSEMODE 


Example 5-1 LAT.C Terminal Driver Programming Example 


#module LAT_FORWARD_CONNECT "X1.0-001"/* 
eH 
kk 


**x MODULE DESCRIPTION: 


*k* 


a In initiating and maintaining an outbound LAT session from the local 
nal node, this program demonstrates the following LAT $QIO functions: 
kk 

“x o Cloning the LAT template devic (LTAO: ) 

ae o IO$SM_LT_SETMODE 

a o IOSM_LT_CONNEC (on forward port) 

ae o IO$M_LT_SENSEMOD 

kk 

kK = 

*/ 

/* 
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*K* 


**x INCLUDE FILES 


K* 
if 
#include 
#include 
#include 
#include 


#include 
#include 


/* 


** 


Terminal Driver 


Terminal Driver Programming Examples 


/* VMS Descriptor Definitions a / 
/* I/O Function Codes Definitions */ 
/* LAT Definitions ae 
/* System Service Return Status Bf 
/* Code Definitions Af 
/* Terminal Characteristics * / 
/* Terminal Extended * / 
/* Characteristics ay 


**x MACRO DEFINITIONS 


** 


ei /- 


/* 


**x Service name which the session will be to. 


*/ 


#define SERVICE_NAME 


#define SERVIC 


/* 


"LAT_SERVICE" 


E NAME LENGTH 11 


** For the sake of clarity, the sizes of the buffers used for reading from 
** and writing to the LTA and TT devices are set to the values below. In 
** order to gain maximum throughput from this program, the following system 
** parameters can be set: 


*K* 


** 


** 


*k* 


1) 
° 


TTY_ALTYPAHD - 1500 
TTY_TYPAHDSZ - 80 


** To get the best performance from this program without touching these 
** system parameters on your system, modify the program to set the size of 


**x the buffers to 


** 
** 


** 


ay 
#define 
#define 
/* 
xx Size 
*/ 


#define 


/* 


o LTA_BUFFER_SIZE 


Li 


the following: 


MIN(TTY_ALTYPAHD, 1500) 


TT_BUFFER_SIZI 


TA_MAXBUF 


TT 


[_MAXBUF 


E = MIN(TTY_TYPAHDSZ, 132) 


1500 
80 


of the LAT SENS 


EFmode itemlist. 


MAX_SENSE_ITEMLIST_SIZE 1500 


** Character user can press to terminate the LAT connection (CTRL+\). 


aya 


#define CONNECTION_TERMINATOR Ox1Cc 
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/* 


** 


** FUNCTION PROTOTYPES 


** 


ad 


unsigned long 
void 
void 
void 
void 
void 
void 


/* 


*K* 


**x GLOBAL DATA 
** 


*/ 


char 


unsigned short 
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SetDeviceChars (void); 
ConnectAST (void) ; 
TAreadChannelAST (void) ; 
TTreadChannelAST (void); 


iE 


LTAhangupHandler (void) ; 
EndSession (void) ; 
ExitHandler (void) ; 


*LTAbuffer, /* LTA device I/O buffer 
*TTbuffer, /* TT device I/O buffer 


/* 


*/ 
ard 


** Text for LAT reject codes. Note that some LAT 
**x implementations will return a 0 reject code to 


*x indicate a normal disconnect. 


ey 


*LATrejectTable[] = { 
"Unknown", 
"User requested disconnect", 
"System shutdown in progress", 
"Invalid slot received", 


"Invalid service class received", 
"Insufficient resources at server", 


"Port or service in use", 
"No such service", 
"Service is disabled", 


"Service is not offeredon the requested 


"Port name is unknown", 
"Invalid service password", 
"Remote entry is not in queue", 
"Immediate access rejected", 
"Access denied", 

"Corrupted request", 


"Requested function is not supported", 


"Session cannot be started", 
"Queu ntry deleted by server", 
"Tllegal request parameters" 


LTAchannel, /* LTA device I/O channel 
TTchannel, /* TT device I/O channel 
LTA_QTOiosb[4], /* IOSB for LTA device functions 


port", 


he 


TT_QIOiosb[4]; /* IOSB for TT device functions 


*/ 
*/ 
*/ 
*/ 
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unsigned long ReadTerminatorMask[2] = { 0, O }, 

/* SQIO read terminator mask */ 
SavedTTdeviceChar [3], 

/* Saved TT device characteristics xf 
DeviceCharBuffSize = sizeof (SavedTTdeviceChar) ; 

/* Size of device characteristics buffer*/ 
ExitConditionValue, /* Exit condition value of program 1 
LATrejectTableSize =/* Number of elements in LAT reject tbl */ 


/* 


sizeof (LATrejectTable) / sizeof (LATrejectTable[0]); 


** Itemlist for setting LAT port with the target service name. 


iy 


struct { 


he 


/* 


unsigned short item_code; 


char 
char 
} PortSetmodelItemlist = { 
LATS$_ITM_TARGET_SERVICE_NAME, SERVICE_NAME LENGTH, SERVICE_NAME 


item_byte_count; 
item_value[ SERVICE_NAME_ LENGTH ]; 


**x Exit handler block. 


*/ 


struct { 


/* 


unsigned long flink; 


void 


(*exit_handler) (); 


unsigned long arg_count; 
unsigned long *exit_status; 
} ExitHandlerBlock = { 0, ExitHandler, 1, ‘7 


** Devices which channels are assigned to. 


ey 


SDESCRIPTOR(LTAtemplateDSC, "LTAO:"); 
SDESCRIPTOR(TTchannelDSC, "SYSS$COMMAND") ; 


main () 


/* 
** Local Variables: 
*/ 
unsigned long status, 
portSetmodeItemlistSize = sizeof (PortSetmodeItemlist) ; 
/* 
**x BEGIN: 


** 


** 


*/ 


Declare an exit handler. 
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if (!( (status = sysS$dclexh() ) & 1) ) 
libSsignal (status); 


/* 
** Assign a channel to LTAO: to get a forward LAT port and assign a 
** channel to the terminal. 


ar 

if (!( (status = sysSassign(, , 0, 0) ) & 1) ) 
libSsignal (status) ; 

if (!( (status = sysSassign(, , 0, 0) ) & 1) ) 
libSsignal (status) ; 

/* 

** Allocate memory for the channel data buffers. 

aa 


LTAbuffer = malloc (LTA_MAXBUF) ; 
TTbuffer = malloc (TT_MAXBUF) ; 


/* 

*x Set device characteristics for the two channels. 

Ly 

if (!( (status = SetDeviceChars() ) & 1) ) 
libSsignal (status); 

/* 


** Do SETmode SQIO to set the port entity with the target service name 
** specified in the item list. 


ef 

if (!( (status = sys$qiow( 
0, 
LTAchannel, 


IO$_TTY_PORT | IOSM_LT_SETMODE, 
~OTOiosb;, 0, Oy 
v 
portSetmodelItemlistSize, 
LATSC_ENT_PORT| (LATSC_ENTS_OLD << 0x10), 
O, O, 0) ) & 1) ) 

libSsignal (status) ; 

if (!(LTA_QIOiosb[0] & 1) ) 
libSsignal (LTA_QIOiosb[0]); 


/* 
*x Enable a CTRL+Y AST on the LAT channel. 
*/ 
if (!( (status = sys$qiow( 
0, 
LTAchannel, 


IO$_SETMODE | IOSM_CTRLYAST, 

-OTOiosb, 0, 0, 

LTAhangupHandler, 

0, O, O, O, 0) ) & 1) ) 
libSsignal (status) ; 
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kk 
xk* 
kk 
kk 
kk 
kk 
kk 
kk 


a 


ad 


unsi 
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if (!(LTA_QIOiosb[0] & 1) ) 
libSsignal (LTA_QIOiosb[0]); 


/* 


**x Post the first read (with AST) on the LTA device to ensure that the 
** first burst of data from the target service is not lost. It is very 
** important that the first read is queued before doing the connect 

xx SQIO to ensure no data lossage. 


*/ 


if (!( (status = sys$qio ( 


0, 

LTAchannel, 

IO0$_READVBLK | IO$M_NOECHO, 
_QIOiosb, 
LTAreadChannelAST, 0, 
LTAbuffer, 

Ly Oy O%:- OY") 1) 7) 


libSsignal (status) ; 


/* 


** Do the LAT connect S$QIO and hibernate until program exit. The 


** ConnectAST will 
*x initial read on 


sa, 


xecute when the connection completes and post the 
the TT channel. 


if (!( (status = sysS$qio ( 


0, 

LTAchannel, 

IO$_TTY_PORT | IOSM_LT_CONNECT, 

_QTOiosb, 

ConnectAST, 0, 0, 0, O, 0, 0, 0) ) & 1) ) 


libSsignal (status) ; 


sysShiber(); 


/* END - main() */ 


FUNCTIONAL DESCRIPTION: 


on the LTA device. 


on the TT device. 


This routine sets device characteristics of the LTA and TT devices. 
The HOSTSYNC, NOBRDCST, EIGHTBIT and PASTHRU characteristics are set 


The ESCAPE and TTSYNC characteristics are cleared. 


The TTISYNC, HOSTSYNC, EIGHTBIT, and PASTHRU characteristics are set 


The ESCAPE characteristic is cleared. The TT 


characterisitcs are also saved for restoration at program exit. 


gned long SetDeviceChars (void) 


/* 


257 


Terminal Driver 
Terminal Driver Programming Examples 


*x Local Variables: 


#/ 


unsigned long status, 
deviceChar[3]; 


/* 
** BEGIN: 
** 


xx Mask and set the characteristics of the LTA device. Sense the 
**x current characteristics, and mask in and set the new ones. 


*/ 

if (!( (status = sys$qiow( 
0, 
LTAchannel, 


IO0$S_SENSEMODE, 
-OTOiosb, 0, 0, 
DeviceCharBuffSize, 0, 0, 0, 0) ) & 1) ) 
libSsignal (status) ; 
if (!(LTA_QIOiosb[0] & 1) ) 


libSsignal (LTA_QIOiosb[0]); 


deviceChar[1] = 


(deviceChar[1] | (TTSM_HOSTSYNC | TISM_NOBRDCST | TTSM_EIGHTBIT) ) 
& ~TTSM_ESCAPE & ~TTSM_TTSYNC; 
deviceChar[2] |= TT2$M_PASTHRU; 
if (!( (status = sys$qiow( 
0, 
LTAchannel, 


IO$_SETMODE, 
&TT_QTOiosb, 0, O, 
&deviceChar 
DeviceCharBuffSize, 0, 0, 0, 0) ) & 1) ) 
libSsignal (status); 
if (!(LTA_QIOiosb[0] & 1) ) 
libSsignal (LTA_QIOiosb[0]); 


/* 
**x Repeat the procedure for TT device characteristics. However, save 
** the current characteristics for restoration at program exit. 
*/ 
if (!( (status = sys$qiow( 
0, 
TTchannel, 


IO$_SENSEMODE, 
STT_QIOiosb, 0, O, 
&SavedTTdeviceChar 
DeviceCharBuffSize, 0, 0, 0, 0) ) & 1) ) 
libSsignal (status) ; 
if (!(TT_QIOiosb[0] & 1) ) 
libSsignal (TT_QIOiosb[0]); 


deviceChar[0] = SavedTTdeviceChar [0]; 
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aH 
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kk 
kk 
kk 
kk 
kk 
xk* 
xK* 
xK* 
xK* 


** 


deviceChar[1] = 
(TTSM_TTSYNC | TTSM_HOSTSYNC | TISM_EIGHTBIT) ) & 


deviceChar[2] = | TT2SM_PASTHRU; 


if 


ALE 


(SavedTTdeviceChar [1] | 


SavedTTdeviceChar [2] 


(!( (status = sys$qiow ( 
0, 
TTchannel, 
IO$_SETMODE, 
&TT_QTOiosb, 
&deviceChar 
DeviceCharBuffSize, 

libSsignal (status); 
(!(TT_QTOiosb[0] & 1) ) 


libSsignal (TT_QIOiosb[0]); 


0, O, 


return (status) ; 


/* 


END - SetDeviceChars */ 


FUNCTIONAL DESCRIPTION: 
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~TTSM_ESCAPE; 


This routine is an AST which executes when the connect SQIO completes. 


First the IOSB is checked. 
simply end the session. 


to exit. 


If the connection timed out or was aborted, 
Any other abnormal status causes the program 


Otherwise the connection completed successfully and a read on the TT 
channel is posted. 


ConnectAST () 


/* 


*K* 


*/ 


unsigned long 


/* 
kk 
** 
** 
*K* 


** 


Ay 


nina 


pine 


Local Variables: 


status; 


BEGIN: 


If the status in the IOSB indicates that the connection timed out 


call the session end routine. 
status causes program exit. 


or aborted, 


== SS$_TIMEOUT) || 


C 


LTA_QIOiosb[0] 
EndSession(); 


(! (LTA_QTOiosb[0] & 1) ) 


(LTA_QTOiosb[0] 


Any other abnormal 


== SSS$_ABORT) ) 


259 


Terminal Driver 
Terminal Driver Programming Examples 


/* 
KES 
kk 
kk 
kk 
kk 
xk* 
Kk 
xK* 


** 
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sysSexit (LTA_QITOiosb[0]); 


/* 
** The connection completed successfully! Post a read (with AST) on 
** the TT device and return. 


*7 


if (!( (status = sys$qio ( 
0, 
TTchannel, 
IO$_READVBLK | I[OSM_NOECHO, 
&TT_QTOiosb, 
TTreadChannelAST, 0, 
TTbuffer, 
1, 0, &ReadTerminatorMask 0, 0) ) & 1) ) 
libSsignal (status) ; 


return; 


/* END - ConnectAST */ 


FUNCTIONAL DESCRIPTION: 


This routine is an AST which executes when the first character read on 
the LTA channel completes. It does a "flush" read of the channel to 
drain any data out of the ALTYPAHD buffer and writes the data to the 
TT channel. It then posts another read on the channel. 


LTAreadChannelAST (void) 


/* 
*x Local Variables: 


e7 
unsigned long status; 


/* 
** BEGIN: 
** 


** Tf the status in the IOSB indicates channel hangup, simply end the 


** session. Signal any other abnormal status. 

*/ 

if (LTA_QIOiosb[0] == SS$_HANGUP) 
EndSession(); 

if (!(LTA_QIOiosb[0] & 1) ) 


libSsignal (LTA_QIOiosb[0]); 


/* 


** Do a "flush" read of the LTA device. This is done by doing a timed 
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** read with a 0 timeout. There may or may not be any data to drain. 
** This method is more efficient than using single character reads. 
*/ 
if (!( (status = sysS$qiow( 
0, 
LTAchannel, 
IO$_READVBLK | IO$M_TIMED | IOSM_NOECHO, 
_QIOiosb, O, O, 
LTAbuffer+l, 
LTA_MAXBUF-1, 0, 
&ReadTerminatorMask, 0, 0) ) & 1) ) 
libSsignal (status); 
if (!(LTA_QIOiosb[0] & 1) && (LTA_QIOiosb[0] != SSS_TIMEOUT) 
libSsignal (LTA_QIOiosb[0]); 
/* 


** The second word of the IOSB contains the number of characters 
** read. Write the characters plus 1 for the initial read to the 


**x TT device. 


*/ 

if (!( (status = sys$qiow( 
0, 
TTchannel, 


IOS_WRITEVBLK, 

~OTOLosb; 0, Oy 

LTAbuffer, 

LTA_QTOiosb[1]+1, 0, 0, 0, 0) ) & 1) ) 
libSsignal (status) ; 

if (!(TT_QIOiosb[0] & 1) ) 
libSsignal (TT_QIOiosb[0]); 


/* 
** Post another read on the LTA device. 
*/ 
if (!( (status = sysSqio ( 
0, 
LTAchannel, 
IO0$_READVBLK | IOSM_NOECHO, 
&LTA_QIOiosb, 
LTAreadChannelAST, 0, 
LTAbuffer, 
1, 0, &ReadTerminatorMask, 0, 0) ) & 1) 
libSsignal (status) ; 
return; 
} /* END - LTAreadChannelAST */ 
/* 
wep 4 
k* 
** FUNCTIONAL DESCRIPTION: 
k* 
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ae This routine is an AST which executes when the first character read on 
ax the TT channel completes. It does a "flush" read of the channel to 
me drain any data out of the TYPAHD buffer and writes the data to the 
ae LTA channel. It then posts another read on the channel. 
kk 
KkKON 
*/ 
void TTreadChannelAST (void) 
{ 

/* 

** Local Variables: 

ay 


unsigned long status; 


/* 
** BEGIN: 
** 


** Tf the user pressed the connection terminator character, do a LAT 
** disconnect SQIO and exit. 


*f 
if (*TTbuffer == CONNECTION_TERMINATOR) 
{ 
if (!( (status = sysS$qiow( 
0, 
LTAchannel, 
IO$_TTY_PORT | IOSM_LT_DISCON, 
_QIOiosb, 0, O, O, O, O, O, 0, 0) ) & 1) ) 
libSsignal (status); 
if (!(LTA_QIOiosb[0] & 1) ) 
lib$signal (LTA_QIOiosb[0]); 
return; 
} 
/* 
** Do a "flush" read of the TT device. This is done by doing a timed 
** read with a 0 timeout. There may or may not be any data to drain. 
*/ 
if (!( (status = sys$qiow( 
0, 
TTchannel, 


IO$_READVBLK | IO$M_TIMED | IOSM_NOECHO, 
_OTOiosb, 0, 0, 
TTbuffert+l, 
TT_MAXBUF-1, 0, 
&ReadTerminatorMask, 0, 0) ) & 1) ) 
libSsignal (status); 
if (!(TT_QIOiosb[0] & 1) && (TT_QIOiosb[0] != SSS$_TIMEOUT) ) 
libSsignal (TT_QIOiosb[0]); 


/* 
** The second word of the IOSB contains the number of characters 
** read. Write the characters plus 1 for the initial read to the 
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*x TT device. 


*/ 
if (!( (status = sysS$qiow ( 
0, 
LTAchannel, 
IOS_WRITEVBLK, 
_OIOiosb, 0, 0, 
buffer, 
_QTOiosb[1]+1, 0, 0, 0, 0) ) & 1) ) 
libSsignal (status) ; 
/* 
** Tf the status in the IOSB indicates channel hangup, simply end 
** the session. Signal any other abnormal status. 
A 
if (LTA_QIOiosb[0] == SSS$_HANGUP) 
EndSession(); 
if (!(LTA_QIOiosb[0] & 1) ) 
libSsignal (LTA_QIOiosb[0]); 
/* 
** Post another read on the LTA device. 
*/ 
if (!( (status = sysS$qio ( 
0, 
TTchannel, 
IO$_READVBLK | IOSM_NOECHO, 
_QIOiosb, 
readChannelAST, 0, 
buffer, 
1, 0, &ReadTerminatorMask, 0, 0) ) & 1) ) 
libSsignal (status) ; 
return; 


/* END - TTreadChannelAST */ 


FUNCTIONAL DESCRIPTION: 


This routine is the CTRL+Y AST for the LTA channel. It executes when 
a hangup on the LTA channel is recognized (connection timed out or 
aborted). It will call the session end routine if it hasn't already 
been called by ConnectAST. 


NOTE: CTRL+Y ASTs for application ports will NOT execute when th 
connection is disconnected. 
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void 


/* 
KES 
kk 
Kk 
xK* 
kk 
kk 
xK* 
Kk 


** 
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LTAhangupHandler (void) 


/* 
** BEGIN: 
** 


** Call the session end routine and return. 


*/ 


EndSession(); 
return; 


/* END - LTAhanghupHandler */ 


FUNCTIONAL DESCRIPTION: 


This routine is executed at session end. It will do a $QIO SENSEmode 
and search the resulting itemlist to find the reason for the LAT 
disconnect. The reason for the disconnect is displayed on the 
terminal and the image exits. 


EndSession (void) 


/* 
** Local Variables: 

/ 

struct ITEM_ENTRY *itemlistEntry; 

unsigned long status; 

char *senseItemlist = malloc (MAX_SENSE_ITEMLIST_SIZE), 


*itemlistEntryPointer; 


/* 
** BEGIN: 
kk 
** Do the SENSEmode on the port. 
*/ 
if (!( (status = sys$qiow( 
0, 
LTAchannel, 
IOS_TTY_PORT | IOSM_LT_SENSEMODE, 
&LTA_QITOiosb, O, O, 
senseItemlist, 
MAX_SENSE_ITEMLIST_SIZE, 
LATSC_ENT_PORT| (LATSM_SENSE_FULL << 0x10), 
O, O, 0) ) & 1) ) 
libSsignal (status); 
if (!(LTA_QIOiosb[0] & 1) ) 


libSsignal (LTA_QIOiosb[0]); 
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/* 
** Set up two pointers used to traverse the itemlist. 

*/ 

itemlistEntry = (struct ITEM_ENTRY *) senseItemlist; 
itemlistEntryPointer = senseItemlist; 

/* 

** Search the itemlist for the LATS_ITM_DISCONNECT_REASON code to find 


** out why the connection terminated. 


Ay 


while (itemlistEntry->LATSR_ITM_CODE.LATSW_ITEMCODE != 
LAT$_ITM_DISCONNECT_REASON) 


/* 
** Tf the current itemcode being checked has a string value, 
** advance the pointer to the next itemcode by skipping 

** BCNT bytes plus 3 bytes for the BCNT byte itself and the 
x** 2 byte itemcode. 


*/. 


if (itemlistEntry-> 
LATSR_ITM_CODE.LATSR_ITM_BITS.LATSV_STRING) 
itemlistEntryPointer += 
itemlistEntry->LATSR_ITEM_VALUE. 
LATSR_ITEM_COUNTED_STRING.LAT$B_ITEM_BCNT + 3; 


/* 
** Tf the current itemcode being checked has a scalar value, 
** advance the pointer to the next itemcode by skipping 6 

** bytes for the itemcode and the 4 byte scalar. 


*/ 
else 
itemlistEntryPointer += 6; 
itemlistEntry = (struct ITEM_ENTRY *) itemlistEntryPointer; 


** If the disconnect reason is a LAT reject code, print out the 
** text corresponding to the code and set the exit condition value 
** to SS$_NORMAL. 


if (itemlistEntry-—>LATSR_ITEM_VALUE.LATSL_ITEM_SCALAR_VALUE <= 
LATrejectTableSize) 


printf("\nSession disconnected. Reason: %s\n\n\n", 
LATrejectTable[ itemlistEntry—>LAT$R_ITEM_VALUE. 
LATS$L_ITEM_SCALAR_ VALUE ]); 
ExitConditionValue = SSS$_NORMAL; 


/* 


** The scalar value is a LAT facility message code. Set the exit 
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** condition value to be the scalar. Upon image exit, the 
** corresponding LAT facility message will be displayed. 


ay 


else 


ExitConditionValue = 
itemlistEntry->LATSR_ITEM_VALUE.LAT$L_ITEM_SCALAR_VALUE; 


sysSexit (ExitConditionValue) ; 


/* END - EndSession */ 


FUNCTIONAL DESCRIPTION: 


This is the program exit handler which is executed upon image exit. 
It will cancel all pending I/O on the two channels and restore the 
TT channel characteristics. 


ExitHandler (void) 


/* 
**x Local Variables: 


*/ 
unsigned long status; 
/* 


** BEGIN: 
** 


** Cancel I/O on the channels, reset terminal characteristics and 
**x return. 


xy 
if (!( (status = sysScancel(LTAchannel) ) & 1) ) 
libSsignal (status) ; 
if (!( (status = sysS$cancel(TTchannel) ) & 1) ) 
libSsignal (status) ; 
if (!( (status = sys$qiow( 
0, 
TTchannel, 


IOS_SETMODE, 
&TT_QTOiosb, 0, O, 
&SavedTTDeviceChar, 
DeviceCharBuffSize, 0, 0, 0, 0) ) & 1) ) 
libSsignal (status) ; 
if (!(TT_QIOiosb[0] & 1) ) 
libSsignal (TT_QIOiosb[0]); 


return; 
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} /* END - ExitHandler */ 


The VAX MACRO program FULL_DUPLEX_TERMINAL.MAR (Example 5-2) shows several I/O operations 
using the full-duplex capabilities of the terminal. This program shows some important concepts about 
terminal driver programming: assigning an I/O channel, performing full-duplex I/O operations, enabling 
Ctrl/C AST requests, and itemlist read operations. The program is designed to run with a terminal set to 
full-duplex mode. 


The initialization code queues a read request to the terminal and enables Ctrl/C AST requests. The main loop 
then prints out a random message every three seconds. When you enter a message on the terminal, the read 
AST routine prints an acknowledgment message and queues another read request. If you press Ctrl/C, the 
associated AST routine cancels the I/O operation on the assigned channel and exits to the command 
interpreter. 


Example 5-2 FULL_DUPLEX_TERMINAL.MAR Terminal Driver Programming Example 


.TITLE FULL_DUPLEX TERMINAL PROGRAMMING EXAMPLI 
-IDENT /05/ 


ee 


KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK 


; TERMINAL PROGRAM 


KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK 


-SBTTL DECLARATIONS 
- DISABLE GLOBAL 


; Declare the external symbols and MACRO libraries. 


. EXTERNAL LIBSGET_EF 
. LIBRARY "SYSSLIBRARY:LIB.MLB' 
. LIBRARY "SYSSLIBRARY:STARLET.MLB' 


; Define symbols 


SIODEF ; Define I/O function codes 

SQIODEF ; Define QIO definition codes 

SSSDEF ; Define the system service status codes 
STRMDEF ; Define itemlist read codes 

STTDEF ; Terminal characteristic definitions 


, 
; Define macros 
, 
. SHOW 
»-MACRO ITEM LEN=0, COD 
. WORD LEN 
. WORD TRMS_'CODE' 
. LONG VALUE 
. LONG 0 


oa 


, VALUE 
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. ENDM ITEM 
- NOSHOW 


, 
; Declare exit handler control block 
, 


EXIT_HANDLER_BLOCK: 


. LONG 0 ; System uses this for pointer 

. LONG EXIT_HANDLER ; Address of exit handler 

. LONG 1 ; Argument count for handler 

. LONG STATUS ; Destination of status code 
STATUS: .BLKL 1 ; Status code from SEXIT 


; Allocate terminal descriptor and channel number storage 


TI_DESC: 
-ASCID /SYSSINPUT/ ; Logical name of terminal 


TT_CHAN: 
. BLKW 1 ; TT channel number storage 


; Define acknowledgment message. This is done right above input buffer 
7 so that we can concatenate the two together when the acknowledgment 
7 message is issued. 


ACK_MSG: 
-ASCII  <CR> /Following input acknowledged: / 
ACK_MSGLEN=.-—-ACK_MSG ; Calculate length of message 


, 
; Allocate input buffer 


a 


IN_BUFLEN = 20 , Set length of buffer 
IN_BUF: 

. BLKB IN_BUFLEN ; Allocate character buffer 
IN_IOSB: 

. BLKQ 1 ; Input I/O status block 


, 
; Define out-of-band ast character mask 
, 
CNTRLA_MASK: 
. LONG 0 
. LONG “B0010 ; Control A mask 


; Define old terminal characteristics buffer 


OLDCHAR_BUF_LEN = 12 
OLDCHAR_BUF: 
. BLKB OLDCHAR_BUF_LEN 
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, 


Define new terminal characteristics buffer 


EWCHAR_BUF_LEN 
EWCHAR_BUF: 


. BLKB 


= 12 


NEWCHAR_BUF_LEN 


Define carriage control symbols 


CR=*X0D 
LF=*X0A 


Define output 


messages 


; Carriage return 
; Line feed 


Output messages are accessed by indexing into a table of 


longwords with each message described by a message address and 


message length 


ARRAY: 
LONG 
LONG 
LONG 
LONG 
LONG 
LONG 
LONG 
LONG 

, 

; Define message 

, 

10S: .- ASCII 

15$=.-10$ 

, 

20S: - ASCII 

25$=.-20$ 

, 

30S: - ASCII 

35S=.-30$ 

, 

40S: - ASCII 


45$=.-40$ 


a 
, 


, 


10$ 
15$ 
208 
25$ 
30$ 
35$ 
40$ 
45$ 


Ss 


; Table of message addresses and 


; lengths 


; First message address 
; First message length 


<CR>/RED ALERT! 


RED ALERT! / 


<CR>/ALL SYSTEMS GO/ 


<CR>/WARNING. . INTRUDER ALARM/ 


<CR>/** SYSTEM OVERLOAD **/ 


Static QIO packet for message output using QIO$_G form 


WRITE_QIO: 


a 


a 


$QIO 


Declare the 


EFN=SYNC__ 
FUNC=I0$_WRIT! 
TOSB=SYNC_ 


EFN, - ; 


IOSB 


required I/O status blocks. 


QIO packet 
EVBLK! IOSM_BREAKTHRU! IOSM_REFR 
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, 


SYNC_IOSB:: . BLKQ al ; I/O status block for synchronous terminal processing. 


, 
; Declare the required event flags. 


a 


ASYNC_EFN:: .BLKL 1 ; Event flag for asynchronous terminal processing. 
SYNC_EFN == WRITE_QIO + 4 ; Event flag for sync terminal processing. 
TIMER_EFN:: . BLKL 1 , Event flag for timer processing. 


, 
; Timer storage 


a 


WAITIME: 

. LONG -10*1000*1000*3,-1 ; 3 second delta time 
TIME: 

. BLKQ 1 ; Current storage time used for 

; random number 

PAGE 

-SBTTL START - MAIN ROUTINE 

»-ENABLE LOCAL BLOCK 
ptt 


, 


, Functional description: 


KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KK KKK KK KKK 


i Start program 


KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK 


; The following code performs initialization functions. 

; It is assumed that the terminal is already in 

; FULL-—DUPLEX mode. 

, 

; NOTE: When doing QIO_S calls, parameters Pl and P3-P6 should be 
; passed by value, while P2 should be passed by reference. 


, Input parameters: 
H None 


; Output parameters: 


7 None 


-ENTRY START “M < > 


Fi Get the required event flags. 


PUSHAL ASYNC_EFN 


CALLS # 1, G* LIBSGET_EF ; Get EFN for async terminal operations. 
BLBC RO, 10$ ; Error - branch. 

PUSHAL SYNC_EFN 

CALLS # 1, G* LIBSGET_EF ; Get EFN for sync terminal operations. 
BLBC RO, 10$ ; Error - branch. 
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PUSHAL TIMER_EFN 
CALLS # 1, G* LIBSGET_EF ; 
BLBC RO, 108 ; 
- Initialize the terminal c 
SASSIGN_S DEVNAM=TT_DESC, -; 
CHAN=TT_CHAN ; 
BLBC RO, 10S ; 
BSBW CHANGE_CHARACTERISTICS A 
; 
BSBW ENABLE CTRLCAST ; 
BSBW ENABLE _OUTBANDAST ; 
BSBW ENABLE READ ; 
MOVZWL TT_CHAN, WRITE_QIO+8 7 
BRB LOOP ; 
108: 
BRW ERROR 


This loop outputs a message based on a 
delays for 3 seconds 


LOOP: 
SGETTIM_S TIMADR=TIME ; 
BLBC RO, 10S ; 
EXTZV #6, #2, TIME, RO ; 
MOVO ARRAY[RO], - ; 
WRITE_QIO+QIOS_P1 ; 
 f 
, 
; Issue QIO write using packet defined in 
, 
SQIOW_G WRITE_QIO 
BLBC RO, 10$ ; 
MOVZWL SYNC_IOSB, RO ; 
BLBC RO, 10$ ; 
, 
; Delay for 3 seconds before issuing next 


SSETIMR_S EFN=TIMER_EFN,- ; 

DAYTIM=WAITIME ; 

; 

BLBC RO, 10$ ; 

SWAITFR_S EFN=TIMER_EFN ; 

BLBS RO, LOOP ; 

BRB 108 i 
. DISABLE LOCAL_BLOCK 
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Get EFN for timer operations. 
Error — branch. 


haracteristics. 


Assign terminal channel using 
logical name and channel number 


Error — branch. 

Change the characteristics of 
terminal 

Allow Ctrl1/C traps 

Enable Ctrl1/A out-of-band AST 
Queue read 

Insert channel into 

static QIO packet 


random number and then 


Get random time 

Error — branch. 

Load random bits into switch 
Load message address 

and size into QIO 

packet 


data area 


QIO error —- branch. 
Get the terminal driver status. 
Terminal driver error —- branch. 


message 


Timer service 

will set event flag 
in 3 seconds 

Error — branch. 
Wait for event flag 
No error if set 
Error — branch. 
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Per 


, 


. PAGE 
.-SBITL 


CHANGE_CHARACTERISTICS - CHANGE CHARACTERISTICS OF TERMINAL 


, Functional description: 


; Input parameters: 


7 Output 


CHANGE_C 


10S: 


ptt 


a 


None 

parameters: 

RO - status from S$QIO call. 

Rl — R5 destroyed 

HARACTERISTICS: 

SQIOW_S EFN=SYNC_EFN, - 
CHAN=TT_CHAN, —- 
FUNC=#1I0$_SENSEMODE, 
IOSB=SYNC_IOSB, —- 
P1=OLDCHAR_BUF, —- 
P2=#OLDCHAR_BUF_LEN 

BLBC RO, 10$ 

MOVZWL SYNC_IOSB, RO 

BLBC RO, 10$ 

SDCLEXH_S EXIT_HANDLER_BLOCK 

BLBC RO, 10$ 

MOVC3 OLDCHAR_BUF_LEN, —- 
OLDCHAR_BUF, —- 
NEWCHAR_BUF 

BISL2 TTSM_NOBRDCST, - 
NEWCHAR_BUF+4 

SQIOW_S EFN=SYNC_EFN, —- 
CHAN=TT_CHAN, —- 
FUNC=#I0S_SETMODE, - 
IOSB=SYNC_IOSB, —- 
P1=NEWCHAR_BUF, —- 
P2=#NEWCHAR_BUF_LEN 

BLBC RO, 10S 

MOVZWL SYNC_IOSB, RO 

BLBC RO, 10S 

RSB 

BRW ERROR 

. PAGE 

.SBITL 


, Functional description: 
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Routine to change the characteristics of the terminal. 


Get current terminal characteristics 


Error if clear 
Get the terminal driver status. 
Error -— branch 


Declare exit handler to reset 
characteristics 

Error — branch. 

Move old characteristics into 
new characteristics buffer 


Set nobroadcast bit 


Set current terminal characteristics 


QIO error —- branch. 
Get the terminal driver status. 
Terminal driver error —- branch. 


ENABLE_CTRLCAST - ENABLE Ctrl1/C AST 


> input 


, Output 
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Routine to allow Ctrl/C recognition. 


parameters: 
None 


parameters: 
None 


ENABLE_CTRLCAST: 


10S: 


ptt 


; Functi 


7; Input 


7 Output 


SQIOW_S EFN=SYNC_EFN, — 
CHAN=TT_CHAN, -— 


FUNC=#I0$_SETMODE! IOSM_CTRLCAST, - 


IOSB=SYNC_IOSB, - 
P1=CTRLCAST, - 


ENABLE_OUTBANDAST: 


10S: 


AST routine address 


P3=#3 User mode 
BLBC RO, 10$ Error — branch. 
MOVZWL SYNC_IOSB, RO Get the terminal driver status. 
BLBC RO, 10$ Terminal driver error —- branch. 
RSB 
BRW ERROR 
PAGE 
.SBITL ENABLE _OUTBANDAST - ENABLE Ctr1/A AST 
onal description: 
Routine to allow CNIRL/A recognition. 
parameters: 
None 
parameters: 
None 
SQIOW_S EFN=SYNC_EFN, - 
CHAN=TT_CHAN, —- 
FUNC=#10$_SETMODE!IOSM_OUTBAND, —- 
TOSB=SYNC_TOSB, - 
P1=CTRLAAST, - AST routine address 
P2=#CNTRLA_MASK, — Character mask 
P3=#3 User mode 
BLBC RO, 10$ QIO error —- branch. 
MOVZWL SYNC_IOSB, RO Get the terminal driver status. 
BLBC RO, 10$ Terminal driver error —- branch. 


RSB 
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BRW ERROR 
. PAGE 
-SBTTL ENABLE READ -— QUEUE A READ TO THE TERMINAL. 


; Functional description: 
; Routine to queue a read operation to the terminal. 


; Input parameters: 
; None 


, Output parameters: 
; None 


; Define item list for itemlist read 


, 


ITEM_LST: 
ITEM 0, MODIFIERS, - ; Convert lowercase to 
TRMSM_TM_CVTLOW! TRMSM_TM_NOEDIT ; upper and inhibit line 
ITEM 6, TERM,MASK_ ADDR ; editing 
; Set up terminator mask 
ITEM_LEN = . -— ITEM_LST 
MASK_ADDR: 
. LONG 1@*XD ; Terminator mask is 
7 <CR> 
. WORD 1@4 ; and "S"ENABLE READ: 
SQIO_S EFN=ASYNC_EFN, — ; Must not be QIOW form or read will block 
CHAN=TT_CHAN, —- ; process 
FUNC=#1I0$_READVBLK! IOSM_EXTEND, —- 
IOSB=IN_IOSB, - 
ASTADR=READAST, - ; AST routine to execute 
P1=IN_BUF, - 7 on 
P2=#IN_BUFLEN, - 
P5=#ITEM_LST, - ; Itemlist read address 
P6=#ITEM_LEN ; Itemlist read size 
BLBC RO, 10$ ; QIO error - branch. 


; The queued read operation will not affect write operations due 
; to the fact that breakthru has been set for the write operations. 


RSB 
108: 
BRW ERROR 
PAGE 
.-SBTTL READAST - AST ROUTINE FOR READ COMPLETION 
.- ENABLE LOCAL_BLOCK 
ptt 


; Functional description: 


Fi AST routine to execute on read completion. 
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; Get the terminal driver status 


; Exit with error status. 


“M < R2, R3, R4, R5 > ; Procedure entry mask 


; Terminal driver error —- branch 

; Get number of characters read into RO 

; Add size of fixed acknowledge message 
- ; Issue acknowledge message 

7 Note, ACK must be asynchronous (QI0O) 


FUNC=#I0O$_WRITEVBLK, - ; and the terminal driver write status 


, Input parameters: 
; None 
, 
, Output parameters: 
; None 
, 
;-- 
, 
108: 
MOVZWL IN_IOSB, RO 
208: 
BRW ERROR 
-ENTRY READAST 
BLBC IN_IOSB, 10S 
MOVZWL IN_IOSB+2, RO 
ADDL2 ACK_MSGLEN, RO 
SQIO_S EFN=ASYNC_EFN, 
CHAN=TT_CHAN, 
P1=ACK_MSG, — 
P2=RO0 
BLBC RO, 20S 


Process read message 


(user-provided code to decode 


; is ignored (no IOSB and AST routine). 
; Specify IOSB and AST routine if output 
7 must be displayed on the terminal. 

; QIO error —- branch 


command inserted here) 


BSBW ENABLE READ ; Queue next read 
RET ; Return to mainline loop 
. DISABLE LOCAL_BLOCK 
. PAGE 
SBTTL CTRLAAST - AST ROUTINE FOR Ctrl1/A 
SBTTL CTRLCAST - AST ROUTINE FOR Ctrl1/C 
SBTTL ERROR —- EXIT ROUTINE 


pot 


, 


, 


Functional des 


AST rout 


Input paramete 
None 


cription: 


ine to execut 


when Ctrl1/C or Ctrl/A is entered. 


rs: 
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, Output parameters: 


; None 
, 
CTRLCAS 
CTRLAAST:: 

.» WORD “M < > 

MOVL #SSS_NORMAL, RO 
ERROR:: 

SEXIT_S RO 

RSB 

. PAGE 

-SBTTL EXIT_HANDLER - 
ptt 


; Functional description: 


EXIT HANDLER ROUTIN 


Procedure entry mask 
Put success in RO 


Exit 


ee | 


7 Exit handler routine to execute when image exits. It cancels 
; any outstanding I/O on this channel and resets the terminal 
: characteristics to their original state. 


; Input parameters: 
; None 


, Output parameters: 
; None 


-ENTRY EXIT_HANDLE 


R 


“M< > 


SCANCEL_S CHAN=TT_CHAN 


SQIOW_S EFN=SYNC_EF 
CHAN=TT_CHA 
FUNC=#1I0$_S 


N, 
N, 


IOSB=SYNC_IOSB, 


P1=OLDCHAR_BUF, 


P2=#OLDCHAR_BUF_L 


BLBC RO, 10$ 

MOVZWL SYNC_IOSB, 
10S: 

RET 

. END START 


RO 


ETMODE, 


’ 


Flush any I/O on queue 
Reset terminal characteristics 


QIO error —- branch. 
Get the terminal driver status. 


The VAX MACRO program READ_VERIFY.MAR (Example 5-3) shows the read verify function. The program 
shows a typical build of itemlists (both the right and left fields), channel assignment, a right- and left-justified 
read verify operation, and then the read QIO operation. 
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Example 5-3 READ_VERIFY.MAR Terminal Driver Programming Example 


. TITLE READ_VERIFY - Read Verify Coding Example 
-IDENT 'V05-000' 


-SBTTL DECLARATIONS 
- DISABLE GLOBAL 


; Declare the external system routines and MACRO libraries. 


. EXTERNAL LIBSGET_EF 

. EXTERNAL SCRSERASE_PAGE 

. LIBRARY "SYSSLIBRARY:LIB.MLB' 

. LIBRARY "SYSSLIBRARY:STARLET.MLB' 


; Include files: 


SIODEF 
STRMDEF 


; Macros: 

, 

»~MACRO ITEM LEN=0, CODE, VALUE 
.» WORD LEN 
.» WORD TRMS_'CODI 
. LONG VALUE 

. LONG 0 

-ENDM ITEM 


ee 


, 

; Equated symbols: 
, 

INBUF_LEN = 20 
ESC = *X1B 


; Own storage: 


; Build item lists for the read verify QIO 


; Right-justified field 


R_ITEM_LIST: 


ITEM CODE = MODIFIERS, —- 

VALUE = TRMSM_TM_R_JUST ; Right justify 
ITEM CODE = EDITMODE, - 

VALUE = TRMSK_EM RDVERIFY ; Enable read verify 
ITEM CODE = PROMPT, 

VALUE = R_PROMPT_ADDR, - 

LEN = R_PROMPT_LEN ; Set up prompt 
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ITEM CODE = INISTRNG, - 

VALUE = R_INISTR_ADDR, - 

LEN = R_INISTR_LEN ; Set up initial string 
ITEM CODE = INIOFFSET, - 

VALUE = R_INISTR_LEN 
ITEM CODE = PICSTRNG, - 

VALUE = R_PICSTR_ADDR, - 

LEN = R_PICSTR_LEN ; Set up picture string 
ITEM CODE = FILLCHR, —- 

VALUE = <*A/* /> ; clear = *, fill = space 


R_ITEM_LIST_LEN R_ITEM_LIST 


R_PROMPT_ADDR: 


-ASCII /[12;12HS$/ 
LEN = .—R_PROMPT_ADDR 


R_PROMP 


R_INISTR_ADDR: 
-ASCII / ’ / 
LEN = .-R_INISTR_ADDR 


R_INISTR 


MASK = TRMSM_CV_NUMERIC! TRM$M_CV_NUMPUNC 


R_PICSTR_ADDR: 
.BYTE 
.BYTE MASK 
.BYTE MASK 
.BYTE 0 ; Marker character 
.BYTE MASK 
.BYTE MASK 
.BYTE MASK 

R_PICSTR_LEN = .-R_PICSTR_ADDR 


’ 
; Left-justified field 
, 
L_ITEM_LIST: 
ITEM CODE = MODIFIERS, - 


VALUE = TRMSM_TM_CVTLOW! TRMSM_TM_AUTO_TAB 
; Upcase input and 
7 complete on field full 
ITEM CODE = EDITMODE, - 
VALUE = TRMSK_EM RDVERIFY ; Enable read verify 
ITEM CODE = PROMPT, 
VALUE = L_PROMPT_ADDR, - 
LEN = L_PROMPT_LEN ; Set up prompt 
ITEM CODE = INISTRNG, - 
VALUE = L_INISTR_ADDR, - 
LEN = L_INISTR_LEN ; Set up initial string 
ITEM CODE = INIOFFSET, - 
VALUE = 0 
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ITEM 


ITEM 


CODE = PICSTRNG, - 
VALUE = L_PICSTR_ADDR, - 

LEN = L_PICSTR_LEN ; 
CODE = FILLCHR, - 

VALUE = <*A/* /> ; 


L ITEM_LIST_LEN = .-L_ITEM_LIST 
L_PROMPT_ADDR 

-ASCII /[13;12H Enter Date: / 
L_PROMPT_LEN = .-—L_PROMPT_ADDR 
L_INISTR_ADDR: 

ASCII / - - / 
L INISTR_LEN = .-L_INISTR_ADDR 
MASK1 = TRMSM_CV_NUMERIC 
MASK2 = TRMS$M_CV_UPPER! TRMSM_CV_LOWER 
L_PICSTR_ADDR: 

.BYTE MASK1 

BYTE MASK1 

. BYTE 0 ; Marker character 

.BYTE MASK2 

.BYTE MASK2 

BYTE MASK2 

. BYTE 0 ; marker character 

BYTE MASK1 

.BYTE MASK1 
L_PICSTR_LEN = .-L_PICSTR_ADDR 
IN_IOSB: »BLKL 2 
TT_CHAN: . BLKW 1 
INBUF: . BLKB INBUF_LEN 
SYSINPUT: -ASCID /SYSSINPUT/ 
SYNC_EFN: » BLKL ll 

. PAGE 

»-ENTRY READ VERIFY “M < > 


; Get the required event flags. 


PUSHAL 
CALLS 
BLBC 


SYNC_EFN 


# 1, 
RO, 


ie 


G* LIBSGET_EF 
RROR ; 


; Assign the channel to SYSS$INPUT 


SASSIGN_S - 


BLBC 


CHAN 


= TI_CHAN - 


DEVNAM = SYSINPUT ; 


RO, 


ERROR ; 
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Set up picture string 


clear = *, fill 


Error — branch 


SYSSINPUT 
Branch on error 
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; Clear the screen 


CLRQ -(SP) 
CALLS #2, G* SCRS 
BLBC RO, ERROR 


ERAS 


E_PAGE 


7 Do the right-justified read operation 


PUSHL #R_ITEM_LIST_LEN 
PUSHAB R_ITEM_LIST 
CALLS #2, DO_READ 

BLBC RO, ERROR 


, 


; Do the left-justified read operation 


, 


PUSHL #L_ITEM_LIST_LEN 
PUSHAB L_ITEM_LIST 
CALLS #2, DO_READ 
BLBC RO, ERROR 
ERROR: 
RET 
. PAGE 
ptt 
; 
; DO_READ - do the actual QIO 
; 
7 Inputs: 
; 
i 4 (AP) 
i 8 (AP) 


-ENTRY DO_READ, 


SQIOW_S EFN=SYNC_EFN, — 


the address of the itemlist 
the length of the itemlist 


CHAN = TT_CHAN, —- 

FUNC = #$_READVBLK! IOSM_EXTEND>, - 

IOSB = IN_IOSB, - 

pl = inbuf, - 

p2 = #inbuf_len, - 

p5 = 4(AP), - 

P6 = 8 (AP) 
BLBC RO, 10$ ; QIO error - branch 
MOVZWL IN_IOSB, RO ; Get the terminal driver status. 
BLBC RO, 1058 ; Terminal driver error - branch 


; Handle the input... 


280 


Terminal Driver 
Terminal Driver Programming Examples 


108: 
RET 
.END READ_VERIFY 
Example 5-4 LIB$XXABLE_CTRL.C Terminal Driver Programming Example 


//Demonstrates CTRL/Y and CTRL/C handling under OpenVMS, as well as 
//some basic dynamic string descriptor operations and a few other 
//string-related operations. 
////To build and use: 
//$ CC/DECC LIB$XXABLE_CTRL 
//$ LINK LIBSXXABLE_CTRL 
//S RUN LIBSXXABLE_CTRL 
*/#include <descrip.h>>#include <iodef.h>>#include <libclidef.h>>#include 
<libSroutines.h>>#include <ssdef.h>>#include <starlet.h>>#include <stdio.h>>#include 
<stsdef.h 
>>void CtrlYHandler () 

{ 

int RetStat; 

SDESCRIPTOR( Y, "<CTRL/Y>>was detected" ); 


RetStat = lib$Sput_output( ); 
if (!SVMS_STATUS_SUCCESS( RetStat ) ) 
return; 


RetStat = libSenable_ctrl( $M_CLI_CTRLY ); 
if (!SVMS_STATUS_SUCCESS( RetStat ) ) 
return; 


return; 


} 


void CtrlCHandler () 
{ 
int RetStat; 
SDESCRIPTOR( Y, "<CTRL/C>>was detected" ); 


RetStat = libSput_output( ); 
if (!'!SVMS_STATUS_SUCCESS( RetStat ) ) 
return; 


RetStat = libSenable_ctrl( $M_CLI_CTRLY ); 
if (!SVMS_STATUS_SUCCESS( RetStat ) ) 
return; 


return; 


} 


main () 
{ 
int RetStat; 
unsigned short int IOChan; 
unsigned short int GotLen; 
struct dsc$descriptor GotDsc = { 0, DSCSK_DTYPE_T, DSCSK_CLASS_D, NULL }; 
SDESCRIPTOR( Prompt, "Enter CTRL/Y, CTRL/C, or any characters and RETURN:" ); 
SDESCRIPTOR( Exiting, "Exiting" ); 
SDESCRIPTOR( TTDsc, "TT:"); 


RetStat = libSdisable_ctrl( $M_CLI_CTRLY ); 
if (!SVMS_STATUS_SUCCESS( RetStat ) ) 
return RetStat; 
RetStat = sysSassign( , , 0, 0 ); 
if (!SVMS_STATUS_SUCCESS( RetStat ) ) 
return RetStat; 
RetStat = sys$qiow( 0, IOChan, IO$_SETMODE|IO$M_CTRLYAST, 0, 0, 0, 


281 


Terminal Driver 
Terminal Driver Programming Examples 


CtrlYHandler, 0, O, O, O, O ); 
if (!SVMS_STATUS_SUCCESS( RetStat ) ) 

return RetStat; 
RetStat = sys$qiow( 0, IOChan, IO$_SETMODE|IOSM_CTRLCAST, 0, 0, 0, 

CtrlCHandler, 0, 0, 0, 0, O ); 
if (!SVMS_STATUS_SUCCESS( RetStat ) ) 

return RetStat; 
RetStat = libSget_input(, , ); 
if (!SVMS_STATUS_SUCCESS( RetStat ) ) 
return RetStat; 
RetStat = sysSdassgn( I0Chan ); 
if (!SVMS_STATUS_SUCCESS( RetStat ) ) 
return RetStat; 
RetStat = libSenable_ctrl( $M_CLI_CTRLY ); 
if (!SVMS_STATUS_SUCCESS( RetStat ) ) 
return RetStat; 
RetStat = libSput_output( ); 
if (!SVMS_STATUS_SUCCESS( RetStat ) ) 
return RetStat; 
RetStat = libSsfreel_dd( ); 
if (!SVMS_STATUS_SUCCESS( RetStat ) ) 
return RetStat; 
return SS$_NORMAL; 
} 
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6 Pseudoterminal Driver 


This chapter describes the use of the pseudoterminal driver (FTDRIVER) and the pseudoterminal software. 


A pseudoterminal is a software device that appears as a real terminal to an application communicating with 
it, but does not require the existence of a physical terminal. A pseudoterminal consists of two components: the 
pseudoterminal device and a control program. The control program acts like a keyboard; that is, anything 
written to the control program appears on the pseudoterminal device as if the keystrokes had been typed in at 
a physical terminal. The control program also acts like a viewport to the pseudoterminal device; that is, the 
control program reads anything that is written by the system to the pseudoterminal device. 


A pseudoterminal allows an application to be set up on the control side of the link to communicate with 
another application that is on the pseudoterminal side. This arrangement allows development of applications 
that either simulate users or monitor the communication between a real user (at a physical terminal) and an 
application. As with other devices, the work of the pseudoterminal is performed by a device driver and is 
tightly coupled to the operating system. 


The pseudoterminal driver software includes a set of control connection routines. Applications can use these 
routines to perform pseudoterminal operations and functions. Appendix D provides the calling conventions 
for these routines. 


6.1 Pseudoterminal Operations 


This section contains information on the following pseudoterminal operations: 
e Creating a pseudoterminal 
e Canceling a request 


e Deleting a pseudoterminal 


6.1.1 Creating a Pseudoterminal 


To create a pseudoterminal, use the PTD$CREATE routine described in Appendix D. When a pseudoterminal 
is created, it inherits the current system terminal default attributes unless you specify an alternate set of 
characteristics. In either case, you cannot use PTD$CREATE to alter the following startup attributes: 


e TT$M_CRFILL is cleared. To change this attribute, issue the SET MODE $QIO function. 
e TT$M_LFFILL is cleared. To change this attribute, issue the SET MODE $QIO function. 
e TT$M_MODEM is cleared. This attribute cannot be changed. 

e TT$M_REMOTE is cleared. This attribute cannot be changed. 

e TT$M_HOSTSYNC is set. To change this attribute, issue the SET MODE $QIO function. 
e TT$M_TTSYNC is set. To change this attribute, issue the SET MODE $QIO function. 


e TT2$M_DMA is cleared. To change this attribute, issue the SET MODE $QIO function. Changing it does 
not alter the behavior of TTDRIVER or the pseudoterminal. 
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e TT2$M_AUTOBAUD is cleared. To change this attribute, issue the SET MODE $QIO function. Changing 
it does not alter the behavior of TTDRIVER or the pseudoterminal. 


e TT2$M_FALLBACK is cleared. To change this attribute, issue the SET MODE $QIO function. 
e TT2$M_HANGUP is cleared. To change this attribute, issue the SET MODE $QIO function. 
e TT2$M_DCL_MAILBxX is cleared. This attribute cannot be changed. 


When you create a pseudoterminal, you can specify a repeating asynchronous system trap (AST) to be 
delivered when the terminal connection is freed. This AST can be supplied only when the pseudoterminal is 
created, and it cannot be deleted. A terminal is freed when a process logs out or deassigns the last channel to 
the device. The AST allows the control program to determine whether or not a user of a pseudoterminal is 
using it. At this point, the control program can reuse or delete the pseudoterminal by deassigning the control 
channel. 


6.1.2 Canceling a Request 


To cancel a queued control connection request, the control program uses the PTD$CANCEL routine. This 
routine enables the pseudoterminal driver to differentiate between control requests and terminal requests 
that are being canceled. This routine cannot be used to flush event notification ASTs. 


6.1.3. Deleting a Pseudoterminal 


To delete the pseudoterminal, the control program uses the PTD$DELETE routine. When a pseudoterminal 
is deleted, any process that is using the pseudoterminal (except the control process) is disconnected. If you 
have the TT2$M_DISCONNECT bit set in the default terminal characteristics parameter (TTY_DEFCHAR2) 
and virtual terminals have been enabled (see Section 5.2.2.3), you get a virtual terminal upon logging in to a 
pseudoterminal. In this case, the process is not logged out, but the virtual terminal is disconnected from the 
pseudoterminal. 


The PTD$DELETE request causes any pending I/O for the control program to be aborted. It deletes any 
queued event notification ASTs and returns the I/O buffers to the application. It also causes the 
pseudoterminal unit control block (UCB) to be deleted once the reference count returns to zero. 


NOTE If an application exits without calling PTD$DELETE, the pseudoterminal is still deleted. 


6.2 Pseudoterminal Driver Features 


The terminal portion of a pseudoterminal is similar to a regular terminal. The pseudoterminal driver 
provides the following features: 


e Type-ahead buffer 

e Specifiable or default line terminators 

e Special operating modes, such as NOECHO and PASTHRU 
e Escape sequence detection 


e = Terminal/mailbox interaction 
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e Terminal control characters, such as Ctrl/S and Ctrl/Q for starting and stopping output, Ctrl/O for 
discarding output, and all other special characters that are handled by the standard terminal driver 


e Limited full-duplex operation (simultaneously active read and write requests) 


For more information on these features, see Section 5.2. 


6.3 Pseudoterminal Driver Device Information 


The pseudoterminal inherits its device characteristics from the system default parameters, with the following 
exceptions: 


e The device inherits initial device characteristics from the SYSGEN-supplied default values. You can 
modify the device characteristics during device creation by supplying new characteristics. 


e The HOSTSYNC terminal characteristic is always set. 
e The device is set to NOMODEM and cannot be set to MODEM. 


e The device is set not to time output character transmission. Hardware controllers time output character 
transmission to determine whether the controller is broken. 


You can obtain information on pseudoterminal characteristics by using the Get Device/Volume Information 
($GETDVI) system service, as described in Section 5.3 and the HP OpenVMS System Services Reference 
Manual. 


Applications should assign a channel other than the control channel to read data from, write data to, read, or 
alter the pseudoterminal characteristics. An attempt to perform such I/O with the control channel, or any 
other attempt to queue an illegal or unsafe I/O request, results in an SS$_CHANINTLK error. 


6.4 V/O Buffers 


When you create a pseudoterminal, you must provide at least one page to be used as an I/O buffer. 
On Alpha and 164 systems, you can allocate one page and divide it into I/O buffers as needed. 


On VAX systems, each page becomes one I/O buffer. You should allocate no more than six I/O buffers for each 
pseudoterminal. 


No read or write request should reference more than one I/O buffer at a time. The I/O buffers must be page 
aligned; therefore, you should create these pages with the $EXPREG system service or the 
LIB$GET_VM_PAGE routine. The pages are owned by the driver until you delete the pseudoterminal. The 
application is responsible for managing the pages and cannot use buffers that are owned by another 
pseudoterminal. The application must decide whether to delete the buffers when they are freed by the driver 
or to reuse them. 


The I/O buffers must be valid pages in virtual address space. Creating or deleting an I/O buffer does not alter 
the contents of the pages. 


The low-order word of the status information longword contains the status of the request. The high-order 
word of the status information longword contains the actual number of bytes that are read or written. 
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Assume that an I/O buffer starting at 200 hexadecimal is available for use. If you want to read 20 bytes from 
the pseudoterminal, the readbuf address would be 200, and the readbuf_len would be 20. An application 
can use the rest of this buffer for other purposes, including reading or writing to the pseudoterminal. 

Figure 6-1 shows how the buffer would look. 


Figure 6-1 Buffer Layout 


Byte Count 


Data 


ZK9656G  E 


6.5 Pseudoterminal Functions 

This section discusses the following pseudoterminal functions: 
e Reading data 

e Writing data 

e Using write with echo 

e Flow control 


e Event notification 


6.5.1 Reading Data 


To read data from the pseudoterminal, the control program uses the PTD$READ routine. The read request 
may complete even when there are no characters available to output. The read operation completes when the 
pseudoterminal has characters to output. If a read request is issued and no data is available, the read request 
is queued and then completed at a later time. 


An application that issues an asynchronous pseudoterminal read can use the $SYNCH system service to find 
out when the read completed. The efn argument for the $SYNCH service must be the same as the efn 
specified in the original PTD$READ call, and the iosb for the $SYNCH service must match the readbuf of 
the PTD$READ call. 


6.5.2 Writing Data 


To write data to the pseudoterminal, the control program uses the PTD$WRITE routine. The write request 
allows you to specify a buffer to receive any output that the write request generates; you do not need to issue 
a separate read request to read this data. When you use an echo buffer, the control application can 
significantly reduce the number of I/O requests required. 
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An application can issue only one write request at a time. Once the write request completes, the application 
must check the write buffer status longword to see whether all the data supplied was written. If not, the 
application must issue additional write requests until all the data has been accepted. 


6.5.3 Using Write with Echo 


If a read request is pending when a write-with-echo request is issued, the echo data is placed in the echo 
buffer. If more data is echoed than can fit in the echo buffer, the remaining data is placed in the pending read 
requests buffer. If no pending read exists, the data is held by the driver until another request that can take 
the data is issued. Both the read and the write with echo must use completion ASTs to allow the driver to 
report request completions to the application in the correct order. 


If an application is not using the write-with-echo capability, the application should avoid using completion 
ASTs if possible. Unnecessary use of completion ASTs significantly increases the number of instructions 
needed to complete a read or write operation. 


When using write with echo, both the wrtbuf and echobuf arguments contain I/O status information. An 
application must check both of these status longwords if the PTD$WRITE completes successfully. If a write 
operation wrote no characters, characters might still be in the echo buffer. If no data was echoed, the status in 
the echobuf is SS$_NORMAL with zero bytes transferred. 


6.5.4 Flow Control 


By default, the driver attempts to notify the control program of data overrun or loss. The pseudoterminal 
sends an XOFF AST when the type-ahead buffer is getting full. Once the pseudoterminal delivers an XOFF 
AST, the pseudoterminal also returns a status of SS$_DATAOVERUN with the actual number of characters 
input. This prevents a single request from flooding the type-ahead buffer. If a control program makes 
repeated attempts to insert data after receiving the SS$_DATAOVERUN message, it can flood the terminal 
type-ahead buffer. When the type-ahead buffer has filled, the pseudoterminal returns the status of 
SS$_DATALOST. 


If the control program is writing to the terminal or terminal driver, it should let the terminal and terminal 
driver handle flow control. To do this, the application should enable all three input flow control notification 
ASTs. The control program should write a DC1 to the terminal if an XON AST is delivered. It should write a 
DC8 to a terminal if an XOFF AST is delivered, and write a BELL character to the terminal if the BELL AST 
is delivered. These signals allow the terminal to decide what to do with the flow control data. The application 
should ignore the SS$_DATAOVERUN and SS$_DATALOST return status and continue writing data to the 
pseudoterminal. 


6.5.5 Event Notification 


This section describes how the pseudoterminal driver provides notification of important driver events. 


6.5.5.1 Input Flow Control 


The driver provides three ways to indicate when the class driver wants to stop input and one way to signal 
when it is safe to resume output: 


e The driver returns a status of SS$_DATAOVERUN and the number of characters input for the control 
program write. 


e The control program can enable a BELL attention AST to be delivered when the class driver calls the 
PTD$SET_TERMINAL_NOTIFICATION routine. This AST is delivered if the pseudoterminal does not 
have the HOSTSYNC attribute set. If only a BELL or only an XOFF AST event is enabled and an XOFF 
or a BELL AST needs to be delivered, the AST that is available is delivered. 
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e The control program can enable an XOFF attention AST to be delivered when the class driver calls the 
PTD$SET_TERMINAL_ NOTIFICATION routine. This AST is delivered if the pseudoterminal has the 
HOSTSYNC attribute set. 


e The control program can enable an XON attention AST to be delivered when the class driver calls the 
PTD$SET_TERMINAL_NOTIFICATION routine. This AST is delivered only if the pseudoterminal has 
the HOSTSYNC attribute set. 


6.5.5.2. Output Stop 


The Output Stop AST tells the control program that the terminal driver is stopping output. This keeps the 
control program from having to determine whether an XOFF written to the control side is being treated by 
the terminal driver as flow control or data. 


6.5.5.3 Output Resume 


The Output Resume AST tells the control program that the terminal driver wants to resume output. This 
AST can be delivered at any time, even if output is active or has previously been stopped. The control program 
should always restart output processing when it receives this AST. 


6.5.5.4 Characteristics Changed 


The Characteristics Changed AST tells the control program that the terminal driver has called the 
pseudoterminal CHANGE CHARACTERISTICS routine. This routine is called whenever the terminal driver 
has changed the device characteristics. The control program should then read the pseudoterminal 
characteristics to determine what has changed. 


6.5.5.5 Output Abort 


The Output Abort AST tells the control program that the terminal driver has called the pseudoterminal 
ABORT OUTPUT routine. This routine is called when the terminal driver wants to flush any outstanding 
output data. The control program should flush any internally buffered data when this AST is received. 


6.5.5.6 Terminal Driver Read Events 


Three special event types notify the control program when a terminal read request starts and finishes. By 
default, the pseudoterminal does not deliver the read notification ASTs associated with these events. The 
PTD$SET_EVENT_NOTIFICATION routine must be used explicitly to enable or disable their delivery. 


e Start Read—Tells the control program that the terminal driver is starting a read request. Some 
applications require this in order to know when to start inputting a logged session script. The special 
event types are: 


e Middle Read—Tells the control program that the terminal driver has finished writing the prompt string if 
one was supplied. 


e End Read—Tells the control program that the terminal driver has finished a read request. 


Once an event notification AST is enabled, it continues to be delivered until it is canceled, or until the device 
is deleted. This characteristic allows the control program to enable the AST once, which greatly reduces the 
risk of missing multiple rapid occurrences of an event. If the driver cannot get sufficient resources to deliver 
the notification AST, that report is lost. Only one AST per event is allowed, and attempts to specify multiple 
ASTs result in use of the last one specified. 


To enable or disable event notification, the control program uses the PTD$SET_EVENT_NOTIFICATION 
routine, which is described in Appendix D. 
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6.6 Pseudoterminal Driver Programming Example 


Example 6-1 shows how to use the pseudoterminal. (The example is also included in the SYS$EXAMPLES 
directory.) This section begins with a brief overview of the example. The example itself briefly discusses each 
module; the pseudocode for that module follows its discussion. 


The scenario chosen for this example is a simple terminal session logging utility that uses most of the 
pseudoterminal capabilities. This example also shows how to use the write-with-echo capability, which 
provides a significant gain in performance. 


6.6.1 Design Overview 


The design approach writes the log record in a main loop that hibernates when it has no work to do. The loop 
uses ASTs to read keystrokes from the terminal, write to the pseudoterminal, and write data to the terminal. 
When a block of characters is written to the terminal, that block is placed into a queue of blocks to be written 
to the log file, and a wake request is issued. Logging is stopped if you log out of the subprocess, if you enter the 
stop logging character Ctrl\, or if a severe error occurs during data processing. When any of these events 
occur, all outstanding log records are written before the program exits. 


One major design consideration is how flow control should be handled — either by attempting to enforce flow 
control, or by letting the terminal and terminal driver handle it. In this example, the terminal and terminal 
driver handle flow control; the driver sends XON, XOFF, or BELL characters to the terminal as necessary. 


One of the six I/O buffers is permanently reserved as the terminal read buffer. This buffer is passed directly to 
the terminal read $QIO. This eliminates having to move data that is read from the terminal into the read 
buffer. The other five buffers are placed in a queue and are allocated and deallocated as needed. This pool of 
buffers reserves the first two longwords to be used as queue headers and traditional IOSBs. The third 
longword and the I/O status longwords are used by the pseudoterminal driver. 


Example 6-1 Sample Pseudocode for Pseudoterminal Driver Program 


/* 

** Main Routine 

K* 

** Function: Intitializes the environment and then hibernates, waiting 

** to be awakened. When awakened, the program checks to see whether it 

** is exiting, or whether more log data is available. If more data is 

** available, the data is appended to the current log record and checked 

** to see whether a log record should be written. A log record is written 

** either when maxbuf characters are in the log buffer, 

** or when it finds a <CR>character pair. The algorithm 

** allows an unlimited number of <NULL> fill characters to occur 

** between the <CR>and the <LF>. If the program is 

** exiting, it closes the log file, deletes the pseudoterminal, resets the 

*x**x terminal, and exits. 

*/ 

Initialize environments (This includes creating pseudoterminal, the log file 
and starting up the subprocess.) 


If (Initialization OK) Then 
Do 
while (I/O buffer to log) 
Data size = number of bytes in I/O buff 
For all data in I/O buffer 
If (cr_seen) Then 


289 


Pseudoterminal Driver 
Pseudoterminal Driver Programming Example 


If (current char == <LF>) Then 
write current log buffer 
reset. cr_seen 
point to start of log buffer 
Else if (current char != <NULL>) Then 
insert <CR>and current char into log buffer 
move log buffer ptr over 2 characters 
reset cr_seen 
Endif 
Else if (current character != <CR>) Then 
insert character into log buffer 
move log buffer ptr over 1 character 
Else 
set cr_seen 
Endif 


If (log buffer ptr >= IOCSGW_MAX-48) Then 
write log buffer 
reset log buffer pointer 
reset cr_seen 
Endif 
Endloop 
Free I/O buffer call free_io_buffers 
Endwhile 
If (not exiting) Then 
Wait for more to do call SYSSHIBER 
Endif 
Until ( (exiting) and (no I/O buffers to log) ) 


close log file 

If ( (close failed) and (exit reason is SSS$_NORMAL) ) Then 
set exit to status to failure reason 

Endif 

If (subprocess still running) Then 

call SYSSFORCEX to run down the subprocess 

Endif 

call PTDSCANCEL to flush all pending pseudoterminal read requests 

call SYSSCANCEL to flush all terminal requests 

call PTDSDELETE to delete the pseudoterminal 

If ( (delete failed) and (exit reason is SS$_NORMAL) ) Then 
set exit to status to failure reason 

Endif 

reset terminal to startup condition using SYSSQIOW 

If ( (terminal reset failed) and (exit reason is SSS$_NORMAL) ) Then 
exit to status to failure reason 

Endif 

Endif 

call LIBSSIGNAL and report exit reason 

Exit 


r 


:3 


/* 

xk 

** Initialization Code 

xk 

** Function: This routine sets the terminal characteristics, creates the 
** pseudoterminal, starts up the subprocess, and opens the log file. If 
** any of these steps fail, the program undoes any steps already done and 
** returns to the main routine. 
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*K* 


*/ 


read the maximum buffer size from IOCSGW_MAXBUF 
Assign a channel to SYSSINPUT 
If (assign ok) Then 
Read the terminal characteristics from the terminal 
If (read of terminal characteristics ok) Then 
Open log file with maximum record size of IOCSGW_MAXBUF 
If (open ok) Then 
Create the pseudoterminal with characteristics of terminal 
If (create ok) then 
Place 4 of the buffers on the queue of free I/O buffers 
Copy terminal characteristics and modify them to NOECHO and PASTHRU 
Set the terminal characteristics use modified value 
If (set ok) Then 
Get device name of pseudoterminal use SYSSGETDVI 
If (get ok) Then 
Create subprocess 
If (create ok) Then 
Enable XON, XOFF, BELL, SET_LINE event notification ASTs 
If (AST setup OK) Then 
Call PTDSREAD to start reading from the pseudoterminal 
ASTADR = ft_read_ast 
ASTPRM = buffer address 
READBUF = I/O buffer + 8 
READBUF_LEN = 500 
If (read ok) Then 
Call SYSSQIO and read a single character from the 
keyboard ASTADR = kbd_read_ast 
If (read failed) Then 
Call PTDSCANCEL to flush queued pseudoterminal read 
Call PTDSDELETE to delete pseudoterminal 
Reset terminal to original state 
Close log file and delete it 
Endif 
Else 
Call PTDSDELETE to delete pseudoterminal 
Reset terminal to original state 
Close log file and delete it 
Endif 
Else 
Call PIDSDELETE to delete pseudoterminal 
Reset terminal to original state 
Close log file and delete it 
Endif 
Else 
Call PTDSDELETE to delete pseudoterminal 
Reset terminal to original state 
Close log file and delete it 
Endif 
Else 
Call PTDSDELETE to delete pseudoterminal 
Reset terminal to original state 
Close log file and delete it 
Endif 
Else 
Call PTDSDELETE to delete pseudoterminal 
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Close log file and delete it 
Endif 
Else 
Close log file and delete it 
Endif 
Endif 
Endif 
Endif 


/* 

** kbd_read_ast 

K* 

** Function: This routine is called every time data is read from the terminal. 
** If the program is exiting, then the routine exits without restarting the 
** read. The character read is checked to see if the terminate processing 
** character Ctrl\ was entered. If the terminate processing character was 
** entered, th xiting state is set and a SYSSWAKE is issued to start the 
** main routine. Now an attempt is made to obtain an I/O buffer in which 
** to store echoed output. If an I/O buffer is unavailable, a simple 

** PTDSWRITE is issued; a PTDSWRITE with echo is issued if a buffer is 

** available. If the write completes successfully, another read is issued 
** to the keyboard. 


** 


*/ 


If (not exiting) Then 
If (read ok) Then 

Search input data for Ctrl\ 

Allocate a read buffer call allocate_io_buffer 

If (got a buffer) Then 

Call PTDSWRITE to write characters to pseudoterminal 

ASTADR = ft_echo_ast 
ASTPRM allocated I/O buffer 
WRTBUF = read I/O buffer 
WRIBUF_LEN = number of characters read 
ECHOBUF = allocated I/O buffer 
ECHOBUF_LEN = 500 


Else 

Call PTDSWRITE to write characters to pseudoterminal 
WRTIBUF = read I/O buffer 
WRIBUF_LEN = number of characters read 


Endif 
If (write setup ok) 
If ( (write status is ok) or (write status is SSS$S_DATALOST) ) 


Issue another single character read to terminal with 
ASTADR = kbd_read_ast, with data going to read I/O buffer 
If (read setup failed) Then 
Set exit flag 
Set exiting reason to SS$_NORMAL 
Endif 
Else 
Set exit flag 
Set exiting reason to SS$_NORMAL 
Endif 
Else 
Set exit flag 
Set exiting reason to SS$_NORMAL 
Endif 
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Else 
Set exit flag 
Set exiting reason to read failure status 
Endif 
If (exiting) Then 
Wake the mainline call SYSSWAKE 
Endif 


Endif 


/* 
xK* 
kk 
kk 
kk 
kk 
kk 
kk 
Kk 
Kk 
Kk 
kk 
*/ 
LE 


terminal_output_ast 


Function: This routine is called every time an I/O buffer is written 
to the terminal. If the terminal write request completes successfully, 
it inserts the I/O buffer into the queue of I/O buffers to be logged. 
If the I/O buffer is the only entry on the queue, it issues a SYSSWAKE 
to start the main routine. To prevent spurious wake requests, 

SYSSWAKE is not issued if multiple entries are already on 

the queue. If a terminal write error occurs, the routine sets the 
exit flag and wakes the main routine. 


(terminal write completed ok) Then 
insert I/O buffer onto logging queue 
If (this is only entry on queue) Then 

wake the mainline call SYSSWAKE 
Endif 


Else 


set exit flag 
set exiting reason to terminal write error reason 
wake the mainline call SYSSWAK 


| 


Endif 


/* 
xK* 
kk 
kk 
kk 
kk 
kk 
kk 
kk 
kk 
*/ 
ft 


ft_read_ast 


Function: This routine is called when a pseudoterminal read request 
completes. It writes the buffer to the terminal and attempts to start 
another read from the pseudoterminal. If the program is not exiting, 
this routine writes the buffer to the terminal and does not start another 
pseudoterminal read. 


(not exiting) 
If (Pseudoterminal read ok) Then 
write buffer to the terminal ASTADR = terminal_output_ast 
If (write setup ok) Then 
Allocate another read buffer call allocate_io_buffer 
If (got a buffer) Then 
Call PTDSREAD to restart reads from the pseudoterminal. 
ASTADR = ft_read_ast 
ASTPRM = buffer address 
READBUF = I/O buffer + 8 
READBUF_LEN = 500 
If (read setup failed) Then 
Set exit flag 
Set exiting reason to read failure reason 
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Wake the mainline call SYSSWAKE 
Endif 
Else 
Set read stopped flag 
Endif 
Else 
Set exit flag 
Set exiting reason to terminal write failure reason 
Wake the mainline call SYSSWAKE 
Endif 
Else 
Set exit flag 


Set exiting reason to terminal read failure reason 
Wake the mainline call SYSSWAKE 
Endif 


Endif 


/* 
** 
** 
** 
** 
** 
** 
*K* 
*K* 
*/ 
If 


ft_echo_ast 


Function: This routine is called if a write to the pseudoterminal used 
an ECHO buffer. If any data was echoed, the output is written to the 
terminal. If no data was echoed, the I/O buffer is freed so it can be 
used later. If the program is exiting, this routine exits. 


(not exiting) Then 
If (ECHO buffer has data) Then 
Write the buffer to the terminal with ASTADR = terminal_output_ast 
If (error setting up write) Then 
Set exit flag 
Set exiting reason to write failure reason 
Wake mainline call SYSSWAKE 
Endif 
Else 
Free I/O buffer call free_io_buffers 
Endif 


Endif 


/* 
xk 
kk 
xK* 
xK* 
kk 
xk 
kk 
*/ 
Lt 


free_io_buffers 


Function: This routine places a free I/O buffer on the queue of available 
I/O buffers. It also restarts any stopped read operations from the 
pseudoterminals. This routine disables AST delivery while it is running 
in order to synchronize reading and resetting the read stopped flag. 


(not exiting) Then 
Disable AST deliver using SYSSSETAST 
If (Pseudoterminal reads not stopped) Then 
Insert I/O buffer on the interlocked queue of free I/O buffers 
Else 
Call PTDSREAD to restart reads from the pseudoterminal. 
ASTADR = ft_read_ast 
ASTPRM buffer address 
READBUF = I/O buffer + 8 
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READBUF_LEN = 500 

If (no error starting read) Then 

Clear read stopped flag 
Else 
Set exit flag 
Set exit reason to read setup reason 
Endif 

Endif 

Enable AST delivery using SYSSSETAST 
Endif 


/* 
k* 
** allocate_io_buffer 
K* 
** Function: This routine obtains a free I/O buffer from the queue of 
** available I/O buffers. If the program is exiting, this routine 
** returns an SS$_FORCEDEXIT error. 
k* 
*/f 
If (not exiting) Then 

remove a I/O buffer from the interlocked queue of I/O buffers 

If (queue empty) Then 

exit with reason LIBS_QUEWASEMP 

else 

exit with reason SSS_FORCEDEXIT 
Endif 


/* 
** subprocess_exit 
k* 
** Function: This routine is called when the subprocess has completed 
** and exited. This routine checks whether the program is already exiting. 
** Tf not, then the routine indicates that the program is exiting and wakes 
** up the main program. 
K* 
Kf 
If (not exiting) Then 
indicate subprocess no longer running 
set exit status to SS$_NORMAL 
indicate exiting 
call SYSSWAKE to start up main loop 
Endif 


/* 
** xon_ast 
k* 
** Function: This routine is called for the pseudoterminal driver to signal 
** that it is ready to accept keyboard input. The routine attempts to send 
** an XON character to the terminal by sending XON DCl using SYSSQIO. 
** Tf the attempt fails, it is not retried. 
K* 
*/ 
If (not exiting) Then 
call SYSSQIO to send a <DCl>character to the terminal 
Endif 


/* 
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** 


*K* 


*K* 


** 


*K* 


** 


** 


bell_ast 


Function: This routine is called when the pseudoterminal driver wants 
to warn the user to stop sending keyboard data. The routine attempts 
to ring the terminal bell by sending the BELL character to the terminal 
using SYSSQIO. If the attempt fails, it is not retried. 


x) 
If (not exiting) Then 
call SYSSQIO to send a <BELL>character to the terminal 
Endif 
/* 
xx xoff_ast 


*K* 


** 


*K* 


** 


** 


** 


Function: This routine is called when the pseudoterminal driver wants to 
signal that it will stop accepting keyboard input. The routine attempts 
to send an XOFF character to the terminal by sending XOFF DC3 to the 
terminal using SYSSQIO. If the attempt fails, it is not retried. 


x) 
If (not exiting) Then 
call SYSSQIO to send a <DC3>character to the terminal 
Endif 
/* 


kk 
kk 
kk 
xK* 
Kk 
xK* 
kk 
kk 
*/ 
lial 


set_line_ast 


Function: This routine is called when the pseudoterminal device 


characteristics change. The routine reads the current pseudoterminal 
characteristics, changes the characteristics to set PASTHRU and NOECHO, 
and applies the characteristics to the input terminal. If the attempt 


to alter the terminal characteristics fails, it is not retried. 


(not exiting) Then 

call SYSSQIOW to read the pseudoterminals characteristics 

If (not error) Then 
Set the alter the just read characteristics to have PASTHRU and NOECHO 
attributes 
call SYSSQIO to set the terminal characteristics. 

Endif 


Endif 
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7 Shadow-Set Virtual Unit Driver 


This chapter provides an overview of HP Volume Shadowing for OpenVMS and describes the use of the 
shadow-set virtual unit driver (SHDRIVER). 


7.1 Introduction 


HP Volume Shadowing for OpenVMS ensures that data is available for applications and end users by 
duplicating data on multiple disks. Because the same data is recorded on multiple disk volumes, if one disk 
fails, the remaining disk or disks can continue to service I/O requests. This ability to shadow disk volumes is 
sometimes referred to as disk mirroring. 


Volume shadowing supports the clusterwide shadowing of DIGITAL SCSI and DSA storage systems. Volume 
shadowing also supports shadowing of all mass storage control protocol (MSCP) served DSA disks and 
DIGITAL SCSI disks. For more information about Volume Shadowing supported devices, refer to the Volume 
Shadowing for OpenVMS Software Product Description. 


You can mount one, two or three compatible disk volumes, including the system disk, to form a shadow set. 
Each disk in the shadow set is known as a shadow set member. Volume Shadowing for OpenVMS logically 
binds the shadow set devices together and represents them as a single virtual device called a virtual unit. 
This means that multiple members of the shadow set, represented by the virtual unit, appear to applications 
and users as a single, highly available disk. 


Volume Shadowing features include: 


e Controller independence. Shadow set members can be located on any node in an OpenVMS Cluster that 
has Volume Shadowing enabled. 


e Clusterwide, homogeneous shadow-set maintenance functions. 
e Ability to survive controller, disk, and media failures transparently. 
e Shadowing functions that do not affect application I/O. 


Applications and users read and write data to and from a shadow set using the same commands and program 
language syntax and semantics that are used for nonshadowed I/O operations. Volume shadowed sets are 
managed and monitored using the same commands and utilities that are used for nonshadowed disks. The 
only difference is that access is through the virtual unit, not to individual devices. 


SHDRIVER, the driver that controls the virtual unit functions, is described in Section 7.3. 


For more detailed information on HP Volume Shadowing for OpenVMS, refer to the Volume Shadowing for 
OpenVMS manual. 
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7.2 Configurations 


HP Volume Shadowing for OpenVMS does not depend on specific hardware in order to operate. All shadowing 
functions can be performed on VAX and Alpha systems running the OpenVMS operating system. Shadow set 
members must have the same physical geometry (that is, the same number of identical logical blocks [LBNs]) 
and members can be located anywhere in an OpenVMS Cluster. 


7.2.1 Supported Hardware 


Volume shadowing requires a minimum of one VAX computer, one mass storage controller, and DSA 
(DIGITAL Storage Architecture) or Small Computer System Interface (SCSD disk drives. 


Refer to the most recent Volume Shadowing for OpenVMS Software Product Descriptions (SPD 27.29.xx ) for 
additional information about hardware requirements. 


7.2.2 Compatible Disk Drives and Volumes 


Volume shadowing requires compatibility among the physical units (disk drives and volumes) that form a 
shadow set. For example: 


e Units must be Files-11 On-Disk Structure Level 2 (ODS-2) data disks. 
e Units and controllers must conform to DSA and OpenVMS MSCP, or must be SCSI compliant. 


e Units should not have hardware write protection enabled. Hardware write protection stops the volume 
shadowing software from maintaining identical volumes. However, the shadow set virtual unit may be 
mounted software write-locked with the /NOWRITE qualifier to MOUNT. 


7.3 Driver Functions 


This section describes the major virtual unit functions supported by SHDRIVER. In addition to the virtual 
unit functions described in this section, SHDRIVER supports all OpenVMS disk functions. SHDRIVER 
receives QIO operations from application programs and is a client of the disk class drivers DUDRIVER. 
Applications access the shadow set as they would access a standard OpenVMS disk. 


Table 7-1 summarizes the major SHDRIVER functions. 


NOTE The MOUNTSHAD, ADDSHADMBR, COPYSHAD, and REMSHADMBR functions are 
reserved for HP internal use. Use of these functions by customer or third-party provided 
software may cause unpredictable results including system crashes and data corruption. 


Table 7-1 Functions of the Shadow Set Virtual Unit Driver 
Function Description 
MOUNTSHAD Creates a virtual unit 
ADDSHAD Evaluates a physical member and adds members 
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Table 7-1 Functions of the Shadow Set Virtual Unit Driver (Continued) 
Function Description 
COPYSHAD Triggers and controls copy operations 
REMSHAD Removes a physical member 
AVAILABLE Virtual unit dissolution 
SENSECHAR Verifies shadow set status 
READ Directs I/O to a physical member 
WRITE Propagates a write operation to all physical members 


7.3.1 Read and Write Functions 


With minor changes, the read and write functions for SHDRIVER operate the same as for the disk class 
driver (see Section 2.4.1 and Section 2.4.2). 


During an SHDRIVER read operation, the host directs the read to the member volume with the shortest 
path. 


During a write operation, SHDRIVER directs the write to each member volume. The write operations for each 
member volume usually proceed in parallel; the virtual unit write operation terminates when all writes have 
completed. The write function for SHDRIVER takes the IO$M_VUEX_FC function modifier; this modifier 
should not be used by application programs. 


The read and write SHDRIVER functions, as well as all user functions, are issued by user programs. All other 
SHDRIVER functions are invoked by MOUNT and DISMOUNT commands, or the $MOUNT and 
$DISMOUNT system services. 


Remember that volume shadowing provides data availability by protecting against hardware problems or 
communication path problems that might cause a disk volume to be a single point of failure. If a write request 
is made to a shadow set, but the system fails before a completion status is returned from all of the shadow set 
members, it is possible that: 


e All members might contain the new data. 
e All members might contain the old data. 
e Some members might contain new data and others might contain old data. 


When the system recovers, volume shadowing performs a merge or copy operation to ensure that the 
corresponding blocks on each shadow set member contain the same data (right or wrong); therefore, the goal 
here is not one of data correctness but of data availability. Volume shadowing is designed to make the data on 
all disks identical, then, if necessary, incorrect data can be reconciled either by the user reentering the data or 
by an application automatically employing database or journaling techniques. 


For example, when used with volume shadowing, OpenVMS RMS journaling allows you to develop 
applications that can automatically recover from failures such as: 


e Permanent loss of the path between a CPU data buffer containing the data being written and the disk 
being written to during a multiple block I/O operation. Communication path loss can occur due to node 
failure or a failure of node-to-node communications. 


e Failure of a CPU (such as a system crash, halt, power failure, or system shutdown) during a multiple 
block write I/O operation. 
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e Mistaken deletion of a file. 
e Corruption of file system pointers. 


¢ OpenVMS RMS file corruption due to a software error or incomplete bucket write operation to an indexed 
file. 


e Cancellation of an in-progress multiple block write operation. 


Refer to the Volume Shadowing for OpenVMS manual for more information about shadowing merge and copy 
operations. 


7.4 Error Processing 


Shadow set recovery and repair are handled by volume processing, which replaces mount verification for 
shadow sets. Membership failure decisions are made by the VAX hosts. Device errors that result in 
inaccessibility of physical member units first utilize the class driver's connection walking algorithm. If that 
fails, a local decision is made on the shadow set membership. The rules are: 


e Ifsome, but not all, members of the set are accessible, then the local node sequentially adjusts the 
membership and notifies the other hosts. 


e Ifno members are accessible, no modifications to the set membership are made. 


There are two types of volume processing: active and passive. Active volume processing handles error 
processing on a local node. Triggered by a failed I/O operation, active volume processing also controls mount 
verification functions, member removal, and failover. Passive volume processing is triggered by lock messages 
or by a cluster event. Passive volume processing revalidates shadow set membership, ensures that the 
shadow set reflects changes made outside the shadow set, and handles the following functions: 


e Member additions from other nodes 

e Member removals from other nodes 

e Anew node mounting the shadow set 

e Anode dismounting the shadow set 

e Asystem crash on a node that has the shadow set mounted 


For more information, refer to the Volume Shadowing for OpenVMS manual. 
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8 Using the OpenVMS Generic SCSI Class 
Driver 


This chapter describes the use of the OpenVMS Generic Small Computer System Interface (SCSI) class 
driver. 


8.1 Overview of SCSI 


The American National Standard for information systems — Small Computer System Interface-2 (SCSI-2) 
specification defines mechanical, electrical, and functional requirements for connecting small computers to a 
wide variety of intelligent devices, such as rigid disks, flexible disks, magnetic tape devices, printers, optical 
disks, and scanners. It specifies standard electrical bus signals, timing, and protocol, as well as a standard 
packet interface for sending commands to devices on the SCSI bus. 


Certain OpenVMS systems employ the SCSI bus as an I/O bus. For these systems, HP offers SCSI-compliant 
disk and tape drives, such as the RZ55 300 MB read/write disk, the RRD40 600 MB compact disk, and the 
TZK50 95 MB streaming tape drive. The operating system also allows devices including disk drives, tape 
drives, and scanners, supplied by sources other than HP, to be connected to the SCSI bus of such a system. 


SCSI has been widely adopted by manufacturers for a variety of peripheral devices; however, because the 
ANSI SCSI standard is broad in scope, not all devices that implement its specifications can fully interrelate 
on the bus. HP fully supports SCSI-compliant equipment sold or supplied by HP. Proper operation of products 
not sold or supplied by HP cannot be assured. 


For more information, refer to the following documents: 


e American National Standard for Information Systems — Small Computer System Interface-2 (SCSI-2) 
specification (X3T9.2/86-109) 


Copies of this document can be purchased from: Global Engineering Documents, 2805 McGaw, Irvine, 
California 92714, United States; or (800) 854-7179 or (714) 261-1455. Please refer to document 
X3.131-198X. 


e American National Standard for Information Systems — Small Computer System Interface specification 
(X3.131-1986) 


Copies of this document can be obtained from: American National Standards Institute, Inc., 1430 
Broadway, New York, New York, 10018. This document is now known as the SCSI-1 standard. 


HP publishes two additional documents to help third-party vendors prepare SCSI peripherals and peripheral 
software for use with DIGITAL workstations. 


e The Small Computer System Interface: An Overview (EK-SCSISOV-001) provides a general description of 
the DIGITAL SCSI third-party support program. 


e The Small Computer System Interface: A Developer's Guide (EK-SCSIS-SP-001) presents the details of 
implementation of SCSI within DIGITAL operating systems. 
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8.2 OpenVMS SCSI Class/Port Architecture 


The operating system employs a class/port driver architecture to communicate with devices on the SCSI bus. 
The class/port design allows the responsibilities for communication between the operating system and the 
device to be cleanly divided between two separate driver modules (see Figure 8-1). 


Figure 8-1 OpenVMS SCSI Class/Port Interface 
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The SCSI port driver transmits and receives SCSI commands and data. It knows the details of transmitting 
data from the local processor's SCSI port hardware across the SCSI bus. Although it understands SCSI bus 
phases, protocol, and timing, it has no knowledge of which SCSI commands the device supports, what status 
messages it returns, or the format of the packets in which this information is delivered. Strictly speaking, the 
port driver is a communications path. When directed by a SCSI class driver, the port driver forwards 
commands and data from the class driver onto the SCSI bus to the device. On any given OpenVMS system, a 
single SCSI port driver handles bus-level communications for all SCSI class drivers that may exist on the 
system. 


The SCSI class driver acts as an interface between the user and the SCSI port, translating an I/O function 
as specified in a user's $QIO request to a SCSI command targeted to a device on the SCSI bus. Although the 
class driver knows about SCSI command descriptor buffers, status codes, and data, it has no knowledge of 
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underlying bus protocols or hardware, command transmission, bus phases, timing, or messages. A single class 
driver can run on any given OpenVMS system, in conjunction with the SCSI port driver that supports that 
system. The operating system supplies a standard SCSI disk class driver and a standard SCSI tape class 
driver to support its disk and tape SCSI devices. 


8.3 Overview of the OpenVMS Generic SCSI Class Driver 


The OpenVMS generic SCSI class driver provides a mechanism by which an application program can control 
a SCSI device, supplied by a source other than HP, that cannot be controlled by the standard OpenVMS disk 
and tape class drivers. By means of a Queue I/O Request ($QIO) system service call, a program can pass to 
the generic SCSI class driver a preformatted SCSI command descriptor block. The generic SCSI class driver, 
in conjunction with the standard OpenVMS SCSI port driver, delivers this SCSI command to the device, 
manages any transfer of data from the device to a user buffer, and returns SCSI status to the application. 


In effect, an application using the generic SCSI class driver implements details of device control usually 
managed within device driver code. The programmer of such an application must understand which SCSI 
commands the device supports and which SCSI status values the device returns. The programmer must also 
be aware of the device's timeout requirements, data transfer capabilities, and command retry behavior. 


The application program sets up the characteristics of the connection the generic SCSI class driver uses when 
delivering commands to, exchanging data with, and receiving status from the device. The program associates 
each I/O operation the device can perform with a specific SCSI command. When it receives a request for a 
particular operation, the application program creates the specific command descriptor block that, when 
passed to the device, causes it to perform that operation. 


The application initiates all transactions to the SCSI device by means of a $QIO call to the generic SCSI class 
driver, supplying the address and length of the SCSI command descriptor block, plus the parameters of any 
data transfer operation, in the call. When the transaction completes and the application program regains 
control, it interprets the returned status value, processes any returned data, and services any failure. To 
avoid conflicts with other applications accessing the same device, an application may need to explicitly 
allocate the device. 


Because the generic SCSI class driver has no knowledge of specific device errors, it neither logs device errors 
nor implements error recovery. An application using the driver must manage device-specific errors itself. To 
service an error returned on a single transaction, the application must issue additional $QIO requests and 
initiate further transactions to the device. If more precise or more efficient error recovery is required for a 
device, the developer should consider writing a third-party SCSI class driver, as described in the OpenVMS 
VAX Device Support Manual (available on the Documentation CD-ROM). A third-party SCSI class driver can 
log errors associated with device activity by using the method described in the OpenVMS VAX Device Support 
Manual (available on the Documentation CD-ROM). 


A third-party class driver is the only means of supporting devices that themselves generate transactions on 
the SCSI bus, such as notification of a device selection event to the host processor. Refer to the description of 
asynchronous event notification (AEN) in the OpenVMS VAX Device Support Manual (available on the 
Documentation CD-ROM). 
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Figure 8-2 shows the flow of a $QIO request through the generic SCSI class driver and the port driver. 


Figure 8-2 Generic SCSI Class Driver Flow 
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When direct access to a target device on the SCSI bus is required, the generic SCSI class driver is loaded for 
that device, as described in Section 8.6. An application program using the generic class driver performs the 
following tasks to issue a command to the target device: 


1. Calls the Assign I/O Channel ($ASSIGN) system service to assign a channel to the generic SCSI class 
driver, and to allocate the device for the application's exclusive use. 


2. Formats a SCSI command descriptor block. 
3. Formats any data to be transferred to the device. 


4. Calls the Queue I/O Request ($QIO) system service to request the generic SCSI class driver to send the 
SCSI command descriptor block to the port driver. 


5. Upon completion of the I/O request, interprets the SCSI status byte and any data returned from the 
target device. 


These operations are described in following sections. 


NOTE Because incorrect or malicious use of the generic SCSI class driver can result in SCSI bus 
hangs and lead to SCSI bus resets, DIAGNOSE and PHY_IO or LOG_IO privileges are 
required to access the driver. An application program can be designed in such a way as to filter 
user I/O requests, which allows nonprivileged users access to some device functions. 


8.4 Accessing the OpenVMS Generic SCSI Class Driver 


Interactive commands and procedure calls can use the OpenVMS generic SCSI class driver to access devices 
on the SCSI bus. However, it is unlikely that a user application would access a device on the SCSI bus by 
directly using the $QIO interface of the generic SCSI class driver. First of all, any user process directly using 
the $QIO interface would require DIAGNOSE and PHY_IO or LOG_IO privileges. Under normal 
circumstances, it would be a system security risk to grant DIAGNOSE and PHY_IO or LOG_IO privileges to 
many system users. Secondly, it would be cumbersome for end users of the device to identify, format, and issue 
SCSI commands to the device. Rather, it would be more efficient to develop an interface that hides these 
details. 


A utility program, installed with the DIAGNOSE and PHY_IO or LOG_IO privileges, can provide 
nonprivileged users with a command-line interface to a SCSI device. The utility translates interactive 
commands provided by the user into the appropriate set of SCSI commands and sends them to the device 
using the $QIO interface provided by the generic SCSI class driver. The utility checks user commands to 
ensure that only valid SCSI commands are sent to the device. Refer to the HP OpenVMS System Manager’s 
Manual and the HP OpenVMS System Management Utilities Reference Manual for information about 
installing images with privileges. 


A privileged shareable image can provide system applications with a procedure interface to a SCSI device. 
The image contains a set of procedures that translate operations specified by the caller into the appropriate 
set of SCSI commands. The SCSI commands are sent to the device through the $QIO interface of the generic 
SCSI class driver. The privileged shareable image checks its caller's parameters to ensure that only valid 
SCSI commands are sent to the device. Refer to the HP OpenVMS Programming Concepts manual for 
information about creating shareable images. 
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8.5 SCSI Port Features Under Application Control 


The standard OpenVMS SCSI port driver provides mechanisms by which the generic SCSI class driver can 
control the nature of data transfers and command transmission across the SCSI bus. An application uses the 
$QIO interface to tailor these mechanisms to the specific device it supports. Among the features under 
application program control are the following: 


e Data transfer mode 

e Disconnection and reselection 
¢ Command retry 

e Command timeouts 


The following sections discuss these features. 


8.5.1 Setting the Data Transfer Mode 


The SCSI bus defines two data transfer modes, asynchronous and synchronous. In asynchronous mode, for 
each REQ from a target there is an ACK from the host prior to the next REQ from the target. Synchronous 
mode allows higher data transfer rates by allowing a pipelined data transfer mechanism where, for short 
bursts (defined by the REQ-ACK offset), the target can pipeline data to an initiator without waiting for the 
initiator to respond. 


Whether or not a port or a target device allows synchronous data transfers, it is harmless for the program to 
set up the connection to use such transfers. If synchronous mode is not supported, the port driver 
automatically uses asynchronous mode. 


For example, to use synchronous mode in a transfer, a programmer using the generic SCSI class driver must 
ensure that both the SCSI port and the SCSI device involved in the transfer support synchronous mode. The 
SCSI port of the VAXstation 3520/3540 system allows both synchronous and asynchronous transfers, whereas 
that of OpenVMS 3100 systems supports only asynchronous transfers. 


To set up a connection to use synchronous data transfer mode, a program using the generic SCSI class driver 
sets the syn bit in the flags field of the generic SCSI descriptor, the address of which is passed to the driver in 
the pl argument to the $QIO request. 


8.5.2 Enabling Disconnection and Reselection 


The ANSI SCSI specification defines a disconnection facility that allows a target device to yield ownership of 
the SCSI bus while seeking or performing other time-consuming operations. When a target disconnects from 
the SCSI bus, it sends a sequence of messages to the initiator that cause it to save the state of the I/O transfer 
in progress. Once this is done, the target releases the SCSI bus. When the target is ready to complete the 
operation, it reselects the initiator and sends to it another sequence of messages. This sequence uniquely 
identifies the target and allows the initiator to restore the context of the suspended I/O operation. 


Whether disconnection should be enabled or disabled on a given connection depends on the nature and 
capabilities of the device involved in the transfer, as well as on the configuration of the system. In 
configurations where there is a slow device present on the SCSI bus, enabling disconnection on connections 
that transfer data to the device can increase bus throughput. By contrast, systems where most of the I/O 
activity is directed towards a single device for long intervals can benefit from disabling disconnection. By 
disabling disconnection when there is no contention on the SCSI bus, port drivers can increase throughput 
and decrease the processor overhead for each I/O request. 
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By default, the OpenVMS class/port interface disables the disconnect facility on a connection. To enable 
disconnection, an application program using the generic SCSI class driver sets the dis bit of the 


flags field of the generic SCSI descriptor, the address of which is passed to the driver in the p1 argument to 
the $QIO call. 


8.5.3 Disabling Command Retry 


The SCSI port driver implements a command retry mechanism, which is enabled on a given connection by 
default. 


When the command retry mechanism is enabled, the port driver retries up to three times any I/O operation 
that fails during the COMMAND, Message, Data, or STATUS phases. For instance, if the port driver detects a 
parity error during the Data phase, it aborts the I/O operation, logs an error, and retries the I/O operation. It 
repeats this sequence twice more, if necessary. If the I/O operation completes successfully during a retry 
attempt, the port driver returns success status to the class driver. However, if all retry attempts fail, the port 
driver returns failure status to the class driver. 


An application may need to disable the command retry mechanism under certain circumstances. For example, 
repeated execution of a command on a sequential device may produce different results than are intended by a 
single command request. A tape drive could perform a partial write and then repeat the write without 
resetting the tape position. 


An application program using the generic SCSI class driver can disable the command retry mechanism by 
setting the dpr bit of the flags field of the generic SCSI descriptor, the address of which is passed to the 
driver in the p1 argument to the $QIO request. 


8.5.4 Setting Command Timeouts 


The SCSI port driver implements several timeout mechanisms, some governed by the ANSI SCSI 
specification and others required by OpenVMS. The timeouts required by OpenVMS include the following: 


Timeout Description 


Phase change timeout Maximum number of seconds for a target to change the SCSI bus phase or 
complete a data transfer. (This value is also known as the DMA timeout.) 


Upon sending the last command byte, the port driver waits this many 
seconds for the target to change the bus phase lines and assert REQ 
(indicating a new phase). Or, if the target enters the DATA IN or DATA 
OUT phase, the transfer must be completed within this interval. 


Disconnect timeout Maximum number of seconds, from the time the initiator receives the 
DISCONNECT message, for a target to reselect the initiator so that it can 
proceed with the disconnected I/O transfer 


An application program using the generic SCSI class driver is responsible for maintaining both of these 
timeout values. It has the following options: 


e Accepting a connection's default value. The default value for both timeouts is 20 seconds. 


e Altering the connection's default value. To modify the default values, the class driver specifies nonzero 
values for the phase change timeout and disconnect timeout fields of the generic SCSI descriptor, 
the address of which is passed to the driver in the p1 argument to the $QIO system service call. 
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8.6 Configuring a Device Using the Generic Class Driver 


On VAX systems, the System Generation utility (SYSGEN) loads the generic SCSI class driver into system 
virtual memory, creates additional data structures for the device unit, and calls the driver's controller 
initialization routine and unit initialization routine. SYSGEN automatically loads and autoconfigures the 
SCSI port driver at system initialization. As part of autoconfiguration, SYSGEN polls each device on each 
SCSI bus. If the device identifies itself as a direct-access device, direct-access CD-ROM device, or flexible disk 
device, SYSGEN automatically loads the disk class driver (DKDRIVER). If the device identifies itself as a 
sequential-access device, SYSGEN automatically loads the tape class driver (MKDRIVER). If the 
autoconfiguration facility does not recognize the type of the SCSI device, it does not load a driver. 


If a third-party-supplied SCSI device requires that the generic class driver be loaded, it must be configured by 
an explicit SYSGEN CONNECT command, as follows: 


S$ RUN SYSSSYSTEM: SYSGEN 
SYSGEN> CONNECT GKpd0u /NOADAPTER 


SYSMAN performs the same functions that SYSGEN performs on VAX systems. If a third-party-supplied 
SCSI device requires that the generic class driver be loaded, the device must be configured by an explicit 
SYSMAN CONNECT command, as follows: 


S$ RUN SYSSSYSTEM: SYSMAN 
SYSMAN> IO CONNECT GKpd0u /NOADAPTER/DRIVER=SYSS$GKDRIVER 


On VAX and Alpha systems, GK is the device mnemonic for the generic SCSI class driver (GKDRIVER); p 
represents the SCSI port ID (for instance, the controller ID A or B ); d represents the SCSI device ID (a digit 
from 0 to 7); 0 signifies the digit zero; and u represents the SCSI logical unit number (a digit from 0 to 7). 


Multiple devices residing on any SCSI bus in the system can share GKDRIVER as a class driver, as long as a 
CONNECT command is issued for each target device that requires the driver. 


Because just one connection can exist through the SCSI port driver to each target, the generic class driver 
cannot be used for a target if a different SCSI class driver is already connected to that target. For example, if 
the SCSI disk class driver has a connection to device ID 2 on the SCSI bus identified by SCSI port ID B 
(DKB200), the generic class driver cannot be used to communicate with this disk. An attempt to connect 
GKDRIVER for this target results in GKB200 being placed off line. 


8.6.1 Disabling the Autoconfiguration of a SCSI Device (VAX Only) 


On VAX systems, in special cases you may need to prevent the autoconfiguration facility from loading the disk 
or tape class driver for a device with a specific port ID and device ID. This would be the case if a SCSI device, 
supplied by a source other than HP, should identify itself as either a random-access or sequential-access 
device and were to be controlled by the generic SCSI class driver. 


To disable the loading of a disk or tape driver for any given device ID, OpenVMS defines the special system 
parameter SCSI_NOAUTO. 


The SCSI_NOAUTO system parameter, as shown in Figure 8-3, stores a bit mask of 32 bits in which the 
low-order byte corresponds to the first SCSI bus (PKAO), the second byte corresponds to the second SCSI bus 
(PKBO), and so on. For each SCSI bus, setting the low-order bit inhibits automatic configuration of the device 
with SCSI device ID 0; setting the second low-order bit inhibits automatic configuration of the device with 
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SCSI device ID 1, and so forth. For instance, the value 000020001, would prevent the device with SCSI ID 5 


on the bus identified by SCSI port ID B from being configured. By default, all of the bits in the mask are 
cleared, allowing all devices to be configured. 


Figure 8-3 SCSI_LNOAUTO System Parameter 


7 07 007 0 7 # SCSI Device ID 


D Cc B A ¢ SCSI Port ID 
ZK1371AGE 


8.7 Assigning a Channel to GKDRIVER 


An application program assigns a channel to the generic SCSI class driver using the standard call to the 
$ASSIGN system service, as described in the HP OpenVMS System Services Reference Manual. The 
application program specifies a device name and a word to receive the channel number. 


8.8 Issuing a $QIO Request to the Generic Class Driver 


The format of the Queue I/O Request ($QIO) system service that initiates a request to the SCSI generic class 
driver is as follows. This explanation concentrates on the special elements of a $QIO request to the SCSI 
generic class driver. For a detailed description of the $QIO system service, refer to the HP OpenVMS System 
Services Reference Manual. 


VAX MACRO Format 
$QIO [efn] ,chan ,func ,iosb ,[astadr] ,[astprm] ,pl ,p2 [,p3] [,p4] [,p5] [,pé] 
High-Level Language Format 


SYSSQIO ([efn] ,chan ,func ,iosb , [astadr] ,[astprm] ,pl ,p2 [,p3] [,p4] [,p5] [,pé6]) 


Arguments 

chan I/O channel assigned to the device to which the request is directed. The 
chan argument is a word value containing the number of the channel, as 
returned by the Assign I/O Channel ($ASSIGN) system service. 

func Longword value containing the IO$_DIAGNOSE function code. Only the 
10$_DIAGNOSE function code is implemented in the generic SCSI class 
driver. 
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iosb 


fefn] 
fastadr] 
fastprm] 
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I/O status block. The iosb argument is required in a request to the generic 
SCSI class driver; it has the following format: 


31 1615 0 
Transfer count VMS stat d IOSB 1 
(loworder ) sale coe 
31 24 23 1615 0 
Transfer count 
ZK1372AGE 


The status code provides the final status indicating the success or failure 
of the SCSI command. The SCSI status byte contains the status value 
returned from the target device, as defined in the ANSI SCSI 
specification. The transfer count field specifies the actual number of bytes 
transferred during the SCSI bus DATA IN or DATA OUT phase 


These arguments apply to $QIO system service completion. For an 
explanation of these arguments, refer to the HP OpenVMS System 
Services Reference Manual. 


pl 


p2 


Descriptor Fields 


opcode 


flags 
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Address of a generic SCSI descriptor of the following format: 
31 0 


SCSI command address 
SCSI command length 
SCSI data address 
SCSI data length 
SCSI pad length 


phase change timeout 


disconnect timeout 


reserved 


ZK1373AGE 


Length of the generic SCSI descriptor. 


Currently, the only supported opcode is 1, indicating a pass-through 
function. Other opcode values are reserved for future expansion. 


Bit map having the following format: 


31 4 83 2 1 0 


ZK1374AGE 
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Bits in the flags bit map are defined as follows: 


Field Definition 


dir Direction of transfer. 


If this bit is set, the target is expected at some time to enter the DATA IN phase to send 
data to the host. To facilitate this, the port driver maps the specified data buffer for write 
access. 


If this bit is clear, the target is expected at some time to enter the DATA OUT phase to 
receive data from the host. To facilitate this, the port driver maps the specified data buffer 
for read access. 


The generic SCSI class driver ignores the dir flag if either the SCSI data address or 
SCSI data length field of the generic SCSI descriptor is zero. 


dis Enable disconnection. 


If this bit is set, the target device is allowed to disconnect during the execution of the 
command. 


If this bit is clear, the target cannot disconnect during the execution of the command. 


Note that targets that hold on to the bus for long periods of time without disconnecting can 
adversely affect system performance. See Section 8.5.2 for additional information. 


syn Enable synchronous mode. 


If this bit is set, the port driver uses synchronous mode for data transfers, if both the host 
and target allow this mode of operation. 


If this bit is clear, or synchronous mode is not supported by either the host or target, the 
port driver uses asynchronous mode for data transfers. 


See Section 8.5.1 for additional information. 
dpr Disable port retry. 


If this bit is clear, the port driver retries, up to three times, any command that fails with a 
timeout, bus parity, or invalid phase transition error. 


If this bit is set, the port driver does not retry commands for which it detects failure. 


See Section 8.5.3 for additional information. 


SCSI command address Address of a buffer containing a SCSI command. 


SCSI command length Length of the SCSI command. The maximum length of the SCSI command 
is 128 bytes. 


SCSI data address Address of a data buffer associated with the SCSI command. 


If the dir bit is set in the flags field, data is written into this buffer during 
the execution of the command. Otherwise, data is read from this buffer 
and sent to the target device. 


If the SCSI command requires no data to be transferred, then the SCSI 
data address field should be clear. 
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SCSI data length 


SCSI pad length 


phase change timeout 


disconnect timeout 
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Length, in bytes, of the data buffer pointed to by the SCSI data address 
field. The maximum data buffer size is 65,535 bytes. 


If the SCSI command requires no data to be transferred, then this field 
should be clear. 


This field is used to accommodate SCSI device classes that require that 
the transfer length be specified in terms of a larger data unit than the 
count of bytes expressed in the SCSI data length field. If the total 
amount of data requested in the SCSI command does not match that 
specified in the SCSI data length field, this field must account for the 
difference. 


For example, suppose an application program is using the generic class 
driver to read the first 2 bytes of a disk block. The length field in the SCSI 
READ command contains 1 (indicating one logical block, or 512 bytes), 
while the SCSI data length field contains a 2. The SCSI pad length 
field must contain the difference, 510 bytes. 


For most transfers, this field should contain 0. Failure to initialize the 
SCSI pad length field properly causes port driver timeouts and SCSI bus 
resets. 


Maximum number of seconds for a target to change the SCSI bus phase or 
complete a data transfer. A value of 0 causes the SCSI port driver's default 
phase change timeout value of 4 seconds to be used. 


See Section 8.5.4 for additional information. 


Maximum number of seconds for a target to reselect the initiator to 
proceed with a disconnected I/O transfer. A value of 0 causes the SCSI port 
driver's default disconnect timeout value of 4 seconds to be used. 


See Section 8.5.4 for additional information. 


8.9 Generic SCSI Class Driver Device Information 


A call to the Get Device/Volume Information ($GETDVD system service returns the following information for 
any device serviced by the generic SCSI class driver. (Refer to the description of the $GETDVI system service 
in the HP OpenVMS System Services Reference Manual.) 


$GETDVI returns the following device characteristics when you specify the item code DVI$_DEVCHAR: 


DEV$M_AVL 
DEV$M_IDV 

DEV$M_ODV 
DEV$M_SHR 


Available device 


Input device 
Output device 


Shareable device 
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DEV$M_RND Random-access device 


DVI$DEVCLASS returns the device class, which is DC$_MISC; DVISDEVTYPE returns the device type, 
which is DT$_GENERIC_SCSI. 


8.10 Call a Generic SCSI Class Driver 


Example 8-1 is an application that uses the generic SCSI class driver to send a SCSI INQUIRY command to a 
device. 


Example 8-1 Generic SCSI Class Driver Call Example 


/* 
GKTEST.C 


This program uses the SCSI generic class driver to send an inquiry command 
to a device on the SCSI bus. 


*/ 
#include ctype 
/* Define the descriptor used to pass the SCSI information to GKDRIVER */ 


#define OPCODE 0 

#define FLAGS 1 

#define COMMAND_ADDRESS 2 
#define COMMAND_LENGTH 3 
#define DATA_ADDRESS 4 
#define DATA_LENGTH 5 
#define PAD_LENGTH 6 

#define PHASE _TIMEOUT 7 
#define DISCONNECT_TIMEOUT 8 


#define FLAGS_READ 1 
#define FLAGS_DISCONNECT 2 


#define GK_EFN 1 


#define SCSI_STATUS_MASK 0X3E 


#define INQUIRY_OPCODE 0x12 
#define INQUIRY_DATA_LENGTH 0x30 


globalvalue 
TOS_DIAGNOSE; 


short 
gk_chan, 


transfer_length; 


int 
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i, 

status, 
gk_device_desc[2], 
gk_iosb[2], 
gk_desc[15]; 


char 
scsi_status, 
ingquiry_command[6] = {INQUIRY_OPCODE, 0, 0, 0, INQUIRY_DATA_LENGTH, 
inquiry_data[INQUIRY_DATA_LENGTH], 
gk_device[] = {"GKAO"}; 
main () 


/* Assign a channel to GKAO */ 


gk_device_desc[0] = 4; 

gk_device_desc[1] = _device[0]; 

status = sysS$assign (_device_desc[0], _chan, 0, 0); 
if (!(status & 1) ) sysSexit (status); 


0}, 


/* Set up the descriptor with the SCSI information to be sent to the target */ 


gk_desc[OPCODE] = 1; 

gk_desc[FLAGS] = FLAGS_READ + FLAGS_DISCONNECT; 
gk_desc[COMMAND_ADDRESS] = _command[0]; 

gk_desc[COMMAND_LENGTH] = 6; 

gk_desc[DATA_ADDRESS] = _data[0]; 

gk_desc[DATA_LENGTH] = INQUIRY_DATA_LENGTH; 

gk_desc[PAD_LENGTH] = 0; 

gk_desc[PHASE_TIMEOUT] = 0; 

gk_desc[DISCONNECT_TIMEOUT] = 0; 

for (i=9; i<15; i++) gk_desc[i] = 0; /* Clear reserved fields */ 


/* Issue the QIO to send the inquiry command and receive the inquiry data */ 


status = sys$qiow (GK_EFN, gk_chan, IOS_DIAGNOSE, gk_iosb, 0, 0, 
_desc[0], 15*4, 0, 0, O, 0); 


/* Check the various returned status values */ 


if (!(status & 1) ) sysSexit (status); 
if (!(gk_iosb[0] & 1) ) sysSexit (gk_iosb[0] & Oxffff); 
scsi_status = (gk_iosb[1] >> 24) & SCSI_STATUS_MASK; 


if (scsi_status) { 
printf ("Bad SCSI status returned: %02.2x\n", scsi_status); 
sysSexit (1); 


/* The command succeeded. Display the SCSI data returned from the target */ 


transfer_length = gk_iosb[0] >> 16; 
printf ("SCSI inquiry data returned: "); 
for (i=0; i<transfer_length; i++) { 
if (isprint (inquiry_data[i]) ) 
printf ("%Sc", inquiry_data[i]); 
else 
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printf ("."); 
} 
printf ("\n"); 
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9 Local Area Network (LAN) Device Drivers 


This chapter describes the use of LAN drivers that support the LAN devices listed in the Software Product 
Description for the OpenVMS Operating System (SPD 82.35.xx). Most of the LAN devices are described here, 
but refer to the Software Product Description for the OpenVMS Operating System for the definitive list of 
supported devices. 


The LAN drivers support two user interfaces or APIs, QIO and VCI (VMS Communications Interface). This 
chapter describes the QIO interface to the LAN drivers, primarily. But most of the QIO functionality applies 
to the VCI interface as well. And the description of the other features and characteristics of the LAN devices 
and LAN drivers applies equally to either interface. 


The LAN drivers are composed of a set of LAN common routines that implement the user interfaces plus a 
LAN port driver for each different type of LAN device. The LAN drivers comprise the Data Link layer as 
defined by the OSI Model defined in Section 9.1. 


9.1 Local Area Network (LAN) Terminology 


The following is a list of terms relevant to local area networks: 


e Ethernet — A network communications technology using coaxial or twisted-pair cable, originally 
developed by Intel, Xerox, and Digital. It has a data transmission rate of 10 megabits/second. It is 
characterized by the use of the CSMA/CD network access method. It is described by the IEEE 802.3 
standard. Ethernet is also used as an adjective to describe Ethernet characteristics, such as an Ethernet 
address, or an Ethernet application... 


e Fast Ethernet — Ethernet upgraded to 100 megabits/second over twisted-pair cable or multimode fiber. 
Fast Ethernet devices support 10 and 100 megabit/second operation over twisted-pair media. 


e Gigabit Ethernet — Ethernet upgraded to 1000 megabits/second over twisted-pair cable or multimode 
fiber. Gigabit Ethernet devices support 10, 100, and 1000megabit/second operation over twisted-pair 
media. 


e FDDIW— Fiber Distributed Data Interface, a token-passing network communications technology 
characterized by use of a dual ring configuration to improve availability upon failure of a node or 
connection. It has a data transmission rate of 100 megabits/second. It operates over multimode fiber or 
twisted-pair cable. It is described by the American National Standards Institute (ANSI) standard 
X3T9.5. 


e Token Ring — A token-passing network communications technology characterized by a star topology in 
most implementations. It has a data transmission rate of 4 or 16 megabits/second. It operates over 
twisted-pair cable. It is described by the IEEE 802.5 standard. 


e ATM — Asynchronous Transfer Mode, a cell-based network communications technology, where network 
data is divided into 48-byte chunks and transfered across the network with a 5-byte header that contains 
addressing and control information. The ATM Forum describes the communications protocol, and 
specifies how it is to be used to interoperate with Ethernet networks, in the LAN Emulation (LANE) 
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standard. To interoperate with Ethernet, the ATM device hardware transparently breaks transmit 
packets into 48-byte chunks plus a 5-byte header and transmits the cells onto the ATM network. On 
receive, it transparently re-assembles the 48-byte chunks to construct each receive packet. 


IEEE — Institute of Electical and Electronics Engineers, an organization that, among other activities, 
develops and maintains standards for the computer and electronics industries, including the 802 
standards that cover local area networking. 


ANSI — American Natioanl Standards Institute, an organization that develops and maintains standards 
for the computer and communications industries 


802.3 — The IEEE standard for Ethernet network technology, including 802.3u for Fast Ethernet, and 
802.3z for Gigabit Ethernet. 


802.5 — The IEEE standard for Token Ring network technology. 


CSMA/CD — Carrier Sense Multiple Access with Collision Detection, the network access protocol used on 
Ethernet networks to resolve contention between nodes competing for access to the network medium. 


NIC — Network Interface Card. Other terms that may be used interchangeably include Adapter, 
Controller, Device, Card, Port. LAN On Motherboard (LOM) is a variant where the NIC hardware is 
included on the system board. A combo adapter consists of multiple adapters on one card, so, for example, 
a quad Ethernet NIC may be referred to as a 4-port card. 


Bus — Data and control paths that connect the functional units of a computer. In relation to LAN devices, 
it refers to the hardware interface between the CPU and the I/O devices. Each LAN device connects to a 
particular type of bus, such as PCI, PCI-X, EISA, ISA, XMI, TurboChannelTurboChannel, each of which 
typically has multiple slots to accomodate several I/O devices. 


Duplex — A characteristic of a 2-way communication channel that indicates whether the channel can 
allow transmission in both directions at the same time (full-duplex) or not (half-duplex). 


Flow Control — A technique where the flow of data along a communications channel is adjusted to ensure 
that the receiving side can handle incoming data without loss. Many network applications implement 
flow control techniques in software. Here, this term refers to the implementation of flow control in 
hardware independent of the network application or protocol, as specified by the IEEE 802.3x standard. 
The receiver side hardware sends special packets, called pause frames, that asks the transmitting side to 
stop transmitting for a specific amount of time. When the receiver has caught up, it sends a pause frame 
with a zero time to re-enable the transmitter. 


Packet — A unit of data transmission on the network, also called frame. It consists of a header, body of 
data, and a Cyclic Redundancy Check (CRC). The frame may be encapsulated by additional data needed 
for the particular network technology. Note that LAN Emulation over ATM imposes packet concepts over 
the underlying cell-based network technology. 


Jumbo Frames — Oversize Ethernet packets, where the range of sizes on Ethernet is from 64-1518 bytes, 
jumbo frames are packets ranging in size from 1519 to 9216 bytes depending on the hardware and 
software implementation. 


Link Up/Down — Network connection state, for Ethernet devices. Most Ethernet devices that connect to 
twisted-pair cables have the ability to detect if an active link connection exists. When both ends of the 
network connection can exchange valid link pulses, the link is considered to be 'up' and the Ethernet 
device is capable of using the network channel to transmit and receive packets. When the Ethernet device 
cannot detect valid link pulses from the other end of the link, the link is considered 'down' and the device 
will not transmit or receive over the network communications path. For Fast Ethernet and Gigabit 
Ethernet, the link connection state is determined by the presence of a carrier signal, for both twisted-pair 
and fiber cabling. 


Ring Available/Unavailable — Network connection state, for FDDI, Token Ring, or ATM devices. 
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e Open Systems Interconnect (OSI) Model - Defines seven layers in a networking framework consisting of: 
— (7) Application Layer 
— (6) Presentation Layer 
— (5) Session Layer 
— (4) Transport Layer 
— (8) Network Layer 
— (2) Data Link Layer 
— (1) Physical Layer 


¢ Port - One end of a communications channel, or the channel itself. When correlated to the OSI Model, 
port may refer to a communications channel at various layers. At the physical layer, a port is a LAN 
device, so a quad Ethernet device is said to be a 4-port card. At the data link layer, the LAN drivers allow 
multiple applications to run on one LAN device. Each application will have opened a port to the LAN 
driver. At the application layer, an application may allow multiple ports to be opened to it, with the 
application itself doing the multiplexing of the ports through itself to the underlying network. An 
example of this would be a network application written to send and receive data over a TCP/IP UDP port. 


In this chapter, applications open a port to the LAN driver to communicate over a particular LAN device. 
In VMS terms, opening a port is done by assigning a channel. 


e User — Refers to the application that has opened a port to the LAN driver. A LAN device may be 
described as having a number of different users. Each user would have opened a port to the LAN device. 
Examples of users are LAT, TCP/IP, DECnet, Clusters (NISCA). 


In this chapter, the terms application and user may be used interchangeably. 


9.2 Supported LAN Devices 
Table 9-1, Table 9-2, Table 9-3,Table 9-4, Table 9-5, and Table 9-6 show the LAN devices supported by the 


OpenVMS operating system. Most of the LAN devices are described here, but refer to the Software Product 
Description for the OpenVMS Operating System (SPD 82.35.xx) for the definitive list of supported devices. 
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9.2.1 OpenVMS VAX LAN Devices 


Table 9-1 and Table 9-2 list the supported devices on OpenVMS VAX systems. Table 9-2 lists additional 
information for the devices listed in Table 9-1. 


Table 9-1 Supported OpenVMS VAX Systems LAN Devices, Part 1 

Medium ae VO Bus Device a shia oe Device Type 
Ethernet 10Base5 XMI DEMNA EXc0 MNA DT$_EX_DEMNA 
Ethernet 10Base2 System SGEC EZc0 ISA DT$_EZ_SGEC 

(LOM) 
Ethernet 10Base2 System LANCE ESc0O SVA DT$_ES_LANCE 
(LOM) 

Ethernet 10Base5 TurboChannel PMAD ECcO MXE DT$_EC_PMAD 
Ethernet 2x10Base5 TurboChannel DELTA ECcO MXE DT$_EC_PMAD 
Ethernet 10Base5 QBUS DESQA EScO SVA DT$_ES_LANCE 
Ethernet 10Base5 QBUS DELQA XQc0 QNA DT$_XQ_ DELQA 
Ethernet 10Base2/5 QBUS DEQTA XQcO0 QNA DT$_XQ DEQTA 
Ethernet 10Base2/5 QBUS DEQNA XQcO0 QNA DT$_DEQNA 
Ethernet 10Base5 QBUS KFE52 EFc0O KFE DT$_FT_NI 
Ethernet 10Base5 XMI DEUNA XEc0 UNA DT$_DEUNA 
Ethernet 10Base5 UNIBUS DELUA XEcO UNA DT$_DELUA 
Ethernet 10Base5 BI DEBNA ETcO BNA DT$_ET_DEBNA 
Ethernet 10Base5 BI DEBNK ETcO BNA DT$_ET_DEBNA 
Ethernet 10Base5 BI DEBNT ETcO BNA DT$_ET_DEBNA 
Ethernet 10Base5 BI DEBNI ETcO BNA DT$_ET_DEBNI 
FDDI 100 mmf XMI DEMFA FXc0 MFA DT$_FX_DEMFA 
FDDI 100 mmf TurboChannel DEFZA FCcO FZA DT$_ FC_DEFZA 
FDDI 100 mmf TurboChannel DEFTA FCc0 FZA DT$ FC _DEFTA 
FDDI 100 mmf QBUS DEFQA FQc0 FQA DT$_FQ DEFQA 
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Device Device Type Version Driver Name 
DEMNA DT$_EX_DEMNA V5.3 EXDRIVER.EXE 
SGEC DT$_EZ_SGEC V5.3 EZDRIVER.EXE 
LANCE DT$_ES_LANCE V4.4 ESDRIVER.EXE 
PMAD DT$_EC_PMAD V5.5-2HW ECDRIVER.EXE 
DELTA DT$_EC_PMAD V5.5-2HW ECDRIVER.EXE 
DESQA DT$_ES_ LANCE V5.0 ESDRIVER.EXE 
DELQA DT$_XQ DELOA V5.0 XQDRIVER.EXE 
DEQTA DT$_XQ DEQTA V5.3 XQDRIVER.EXE 
DEQNA DT$_DEQNA V4.0 XQDRIVER.EXE 
KFE52 DT$_FT_NI V5.4 EFDRIVER.EXE/EPDRIVER.EXE 
DEUNA DT$_DEUNA V4.0 XEDRIVER.EXE 
DELUA DT$_DELUA V4.0 XEDRIVER.EXE 
DEBNA DT$_ET_DEBNA V4.4 ETDRIVER.EXE 
DEBNK DT$_ET_DEBNA V4.4 ETDRIVER.EXE 
DEBNT DT$_ET_DEBNA V4.4 ETDRIVER.EXE 
DEBNI DT$_ET_DEBNI V5.2 ETDRIVER.EXE 
DEMFA DT$_FX_DEMFA V5.4-3 FXDRIVER.EXE 
DEFZA DT$_FC_DEFZA V5.5-2HW FCDRIVER.EXE 
DEFTA DT$_FC_DEFTA V6.0 FCDRIVER.EXE 
DEFQA DT$_FQ DEFQA V6.1 FQDRIVER.EXE 


DEQTA is also known as the DELQA-YM. 


PMAD is a single LANCE device. 
DELTA is a dual LANCE device. 


10Base2 is also known as BNC or Thinwire. 
10Base5 is also known as AUI or Thickwire. 


100 mmf is 100 megabits/second multimode fiber. 
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9.2.2 OpenVMS Alpha LAN Devices 
Table 9-3 and Table 9-4 list LAN devices supported on OpenVMS Alpha. Table 9-4 lists additional 


information for the devices listed in Table 9-3. 


Table 9-3 Supported OpenVMS Alpha LAN Devices, Part 1 
Medium ee VO Bus Device ee a Device Type 
Ethernet 10Base5 XMI DEMNA EX MNA DT$_EX_DEMNA 
Ethernet 10Base2/5 CBUS TGEC EZ ISA DT$_EZ_TGEC 
(LOM) 
Ethernet 10Base2 TurboChannel COREIO ES SVA DT$_ES_LANCE 
(COM) 
Ethernet 10Base5 TurboChannel PMAD EC MXE DT$_EC_PMAD 
Ethernet 2x10Base5 TurboChannel DELTA EC MXE DT$_ EY NITC2 
Ethernet 10Base2/T EISA DE422 ER ERA DT$_ER_DE422 
Ethernet 10Base2/5/T EISA DE425 ER ETA DT$_ER_TULIP 
Ethernet 10Base2/5 ISA DE200 ER ERA DT$_ER_LANCE 
Ethernet 10BaseT ISA DE201 ER ERA DT$_ER_LANCE 
Ethernet 10Base2/T ISA DE202 ER ERA DT$_ER_LANCE 
Ethernet 10Base2/5/T ISA DE203 ER ERA DT$_ER_LEMAC 
Ethernet 10BaseT ISA DE204 ER ERA DT$_ER_LEMAC 
Ethernet 10Base2/5/T ISA DE205 ER ERA DT$_ER_LEMAC 
Ethernet 10BaseT PCI Tulip EW EWA DT$_EW_TULIP 
(LOM) 
Ethernet 10BaseT PCI DE434 EW EWA DT$ EW _DE435 
Ethernet 10Base2/5/T PCI DE435 EW EWA DT$_EW_DE485 
Ethernet 4x10BaseT PCI DE436 EW EWA DT$ EW _DE435 
Ethernet 10Base2/5/T PCI DE450 EW EWA DT$_EW_DE450 
Ethernet 100BaseTX PCI DE500-XA EW EWA DT$_EW_DE500 
Ethernet 100BaseTX PCI DE500-AA EW EWA DT$_EW_DE500 
Ethernet 100BaseTX PCI DE500-BA EW EWA DT$_EW_DE500 
Ethernet 100BaseFX PCI DE500-FA EW EWA DT$_EW_DE500 
Ethernet 4x PCI P2SE+ EW EWA DT$_EW_DE500 
100BaseTX 
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Table 9-3 Supported OpenVMS Alpha LAN Devices, Part 1 (Continued) 
Medium oe V/O Bus Device UpenyMS:. PEOnet Device Type 
Type Name Name 
Ethernet 10BaseT PCI 21142 EW EWA DT$ EW_DE500 
(LOM) 
Ethernet 100BaseTX PCI DE504-BA EW EWA DT$_EW_DE500 
Ethernet 10Base2/5/T, PCI P2SE EW EWA DT$_EW_DE500 
100BaseTX 
Ethernet 10Base2/5/T, PCI 21143 EW EWA DT$_EW_DE500 
100BaseTX (LOM) 
Ethernet 100BaseTX PCI DE600-AA EI EIA DT$_EI 82558 
Ethernet 100BaseTX PCI DE602-AA EI EIA DT$_EI 82558 
Ethernet 2x PCI DE602-BA EI EIA DT$_EI_ 82558 
100BaseTX 
Ethernet 2x PCI DE602-BB EI EIA DT$_EI_82559 
100BaseTX 
Ethernet 2x DE602 DE602-TA EI EIA DT$_EI_82559 
100BaseTX daughter card 
Ethernet 100BaseFX DE602 DE602-FA EI EIA DT$_EI 82558 
daughter card 
Ethernet 100BaseTX PCI Trifecta EI EIA DT$_EI 82558 
Ethernet 100BaseTX PCI 82559ER EI EIA DT$_EI_82559 
(LOM) 
Ethernet 1000BaseSX PCI DEGPA-SA EW EWA DT$_EW_DEGPA 
Ethernet 1000BaseTX PCI DEGPA-TA EW EWA DT$_EW_DEGPA 
Ethernet 1000BaseSX PCI DEGXA-SA EW EWA DT$_EW_BCM5703 
Ethernet 1000BaseTX PCI DEGXA-TA EW EWA DT$_EW_BCM5703 
Ethernet 1000BaseSX PCI-X DEGXA-SB EW EWA DT$_EW_BCM5703 
Ethernet 1000BaseTX PCI-X DEGXA-TB EW EWA DT$_EW_BCM5703 
Ethernet 1000BaseTX PCI BCM5703 EW EWA DT$_EW_BCM5703 
(LOM) 
Ethernet 10Base2/T PCMCIA 3C589B EO CEC DT$_EO_3C589 
Ethernet 10Base2/T PCMCIA 3C589D EO CEC DT$_EO_38C589 
Ethernet N/A Memory Galaxy EB EBA DT$_EB_SMLAN 
Shared 
Memory 
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Table 9-3 Supported OpenVMS Alpha LAN Devices, Part 1 (Continued) 
Medium oe V/O Bus Device UpenyMS:. PpOnet Device Type 
Type Name Name 
FDDI 100 mmf XMI DEMFA FX MFA DT$_FX_DEMFA 
FDDI 100 mmf FutureBus+ DEFAA FA FAA DT$_FA_DEFAA 
FDDI 100 mmf TurboChannel DEFZA FC FZA DT$_FC_DEFZA 
FDDI 100 mmf - TurboChannel DEFTA-AA FC FZA DT$_FC_DEFTA 
SAS 
FDDI 100 mmf - TurboChannel DEFTA-DA FC FZA DT$ FC _DEFTA 
DAS 
FDDI UTP - SAS TurboChannel DEFTA-UA FC FZA DT$_FC_DEFTA 
FDDI 100 mmf - EISA DEFEA-AA- FR FEA DT$_FR_DEFEA 
SAS 
FDDI 100 mmf - EISA DEFEA-DA FR FEA DT$_FR_DEFEA 
DAS 
FDDI UTP - SAS EISA DEFEA-UA FR FEA DT$_FR_DEFEA 
FDDI UTP - DAS EISA DEFEA-MA FR FEA DT$_FR_DEFEA 
FDDI 100 mmf - PCI DEFPZ-AA FW FPA DT$_FW_DEFPA 
SAS 
FDDI UTP - SAS PCI DEFPZ-UA FW FPA DT$_FW_DEFPA 
FDDI 100 mmf - PCI DEFPA-AA/ FW FPA DT$_FW_DEFPA 
SAS AB/AC 
FDDI 100 mmf - PCI DEFPA-DA/ FW FPA DT$_FW_DEFPA 
DAS DB/DC 
FDDI UTP - SAS PCI DEFPA-UA/ FW FPA DT$_FW_DEFPA 
UB/UC 
FDDI UTP - DAS PCI DEFPA-MA FW FPA DT$_FW_DEFPA 
/MB/MC 
TokenRing 4/16 TurboChannel DETRA IC TRA DT$ IC_DETRA 
STP/UTP 
TokenRing 4/16 EISA DW300 IR TRE DT$_IR_DW300 
STP/UTP 
TokenRing 4/16 ISA DW110 IR TRE DT$_IR_DW300 
STP/UTP 
TokenRing 4/16 PCI TC4048 IW TRE DT$_IW_TI380PCI 
STP/UTP 
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Table 9-3 Supported OpenVMS Alpha LAN Devices, Part 1 (Continued) 
Medium Pee V/O Bus Device a oo Device Type 
TokenRing 4/16 PCI M8154 IW TRE DT$_IW_TI380PCI 
STP/UTP 
ATM 155 mmf TurboChannel DGLTA HC/EL ELA DT$_HC_OTTO 
ATM 155 mmf PCI DGLPB HW/EL ELA DT$_HW_OTTO 
ATM 155 mmf PCI DGLPA-FA HW/EL ELA DT$_HW_METEOR 
ATM UTP PCI DAPBA-UA HW/EL ELA DT$_HW_HE155 
ATM 155 mmf PCI DAPBA-FA HW/EL ELA DT$_HW_HE155 
ATM UTP PCI DAPBA-UA HW/EL ELA DT$_HW_HE155 
ATM 622 mmf PCI DAPCA-FA HW/EL ELA DT$_HW_HE622 
Table 9-4 Supported OpenVMS Alpha LAN Devices, Part 2 
Device Device Type Version Driver Name 
DEMNA DT$_EX_DEMNA V1.0 SYS$EXDRIVER.EXE 
TGEC (LOM) DT$_EZ_TGEC V1.0 SYS$EZDRIVER.EXE 
COREIO (LOM) DT$_ES_LANCE V1.0 SYS$ESDRIVER.EXE 
PMAD DT$_EC_PMAD V1.0 SYS$ECDRIVER.EXE 
DELTA DT$_EY_NITC2 V6.1 SYS$ECDRIVER.EXE 
DE422 DT$_ER_DE422 V1.5 SYS$ERDRIVER.EXE 
DE425 DT$_ER_TULIP V6.1 SYS$ERDRIVER.EXE 
DE200 DT$_ER_LANCE V6.1 SYS$ERDRIVER.EXE 
DE201 DT$_ER_LANCE V6.1 SYS$ERDRIVER.EXE 
DE202 DT$_ER_LANCE V6.1 SYS$ERDRIVER.EXE 
DE203 DT$_ER_LEMAC V6.2 SYS$ERDRIVER.EXE 
DE204 DT$_ER_LEMAC V6.2 SYS$ERDRIVER.EXE 
DE205 DT$_ER_LEMAC V6.2 SYS$ERDRIVER.EXE 
Tulip (LOM) DT$_EW_TULIP V6.1 SYS$EWDRIVER.EXE 
DE434 DT$_EW_DE435 V6.1 SYS$EWDRIVER.EXE 
DE435 DT$_EW_DE435 V6.1 SYS$EWDRIVER.EXE 
DE436 DT$_EW_DE435 V6.1 SYS$EWDRIVER.EXE 
DE450 DT$_EW_DE450 V6.2 SYS$EWDRIVER.EXE 
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Device Device Type Version Driver Name 
DE500-XA DT$_EW_DE500 V6.2 SYS$EWDRIVER.EXE 
DE500-AA DT$_EW_DE500 V7.1 SYS$EWDRIVER.EXE 
DE500-BA DT$_EW_DE500 V7.1-1H1 SYS$EWDRIVER_DE500BA.EXE 
DE500-FA DT$_EW_DE500 V7.1-1H1 SYS$EWDRIVER.EXE 
DE504-BA DT$_EW_DE500 V7.1-1H1 SYS$EWDRIVER_DE500BA.EXE 
P2SE DT$_EW_DE500 V7.1-1H1 SYS$EWDRIVER.EXE 
P2SE+ DT$_EW_DE500 V7.1-1H1 SYS$EWDRIVER.EXE 
21142 (LOM) DT$_EW_DE500 V7.1-1H1 SYS$EWDRIVER_DE500BA.EXE 
21143 (LOM) DT$_EW_DE500 V7.1-1H1 SYS$EWDRIVER_DE500BA.EXE 
DE600-AA DT$_EI_82558 V7.2 SYS$EIDRIVER.EXE 
DE602-AA DT$_EI_82558 V7.2 SYS$EIDRIVER.EXE 
DE602-BA DT$_EI_82558 V7.2 SYS$EIDRIVER.EXE 
DE602-BB DT$_EI_82559 V7.2 SYS$EIDRIVER.EXE 
DE602-TA DT$_EI_82559 V7.2 SYS$EIDRIVER.EXE 
DE602-FA DT$_EI_82558 V7.2 SYS$EIDRIVER.EXE 
Trifecta DT$_EI_82558 V7.2 SYS$EIDRIVER.EXE 
82559ER (LOM) DT$_EI_82559 V7.3-1 SYS$EIDRIVER.EXE 
DEGPA-SA DT$_EW_DEGPA V7.1-2 SYS$EW1000A.EXE 
DEGPA-TA DT$_EW_DEGPA V7.1-2 SYS$EW1000A.EXE 
DEGXA-SA DT$_EW_BCM5703 __-V7.2-2 SYS$EW5700.EXE 
DEGXA-TB DT$_EW_BCM5703 __-V7.2-2 SYS$EW5700.EXE 
DEGXA-SB DT$_EW_BCM5703 __-V7.2-2 SYS$EW5700.EXE 
DEGXA-TB DT$_EW_BCM5703 _—-V7.2-2 SYS$EW5700.EXE 
BCM5703 (LOM) DT$_EW_BCM5703  V7.3-1 SYS$EW5700.EXE 
3C589B DT$_EO_8C589 V6.2-1H2 SYS$EODRIVER.EXE 
3C589D DT$_EO_8C589 V6.2-1H2 SYS$EODRIVER.EXE 
Galaxy Shared DT$_EB_SMLAN V7.2 SYS$EBDRIVER.EXE 
Memory 
DEMFA DT$_FX_DEMFA V1.0 SYS$FXDRIVER.EXE 
DEFAA DT$_FA_DEFAA V1.0 SYS$FADRIVER.EXE 
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Table 9-4 Supported OpenVMS Alpha LAN Devices, Part 2 (Continued) 
Device Device Type Version Driver Name 

DEFZA DT$_FC_DEFZA V1.0 SYS$FCDRIVER.EXE 
DEFTA-AA DT$_FC_DEFTA V1.0 SYS$FCDRIVER.EXE 
DEFTA-DA DT$_FC_DEFTA V1.0 SYS$FCDRIVER.EXE 
DEFTA-UA DT$_FC_DEFTA V6.1 SYS$FCDRIVER.EXE 
DEFEA-AA DT$_FR_DEFEA V1.5 SYS$FRDRIVER.EXE 
DEFEA-DA DT$_FR_DEFEA V6.1 SYS$FRDRIVER.EXE 
DEFEA-UA DT$_FR_DEFEA V6.1 SYS$FRDRIVER.EXE 
DEFEA-MA DT$_FR_DEFEA V6.1 SYS$FRDRIVER.EXE 
DEFPZ-AA DT$_FW_DEFPA V6.1 SYS$FWDRIVER.EXE 
DEFPZ-UA DT$_FW_DEFPA V6.2 SYS$FWDRIVER.EXE 
DEFPA-AA/AB/AC DT$_FW_DEFPA V6.2 SYS$FWDRIVER.EXE 
DEFPA-DA/DB/DC DT$_FW_DEFPA V6.2 SYS$FWDRIVER.EXE 
DEFPA-UA/UB/UC DT$_FW_DEFPA V6.1 SYS$FWDRIVER.EXE 
DEFPA-MA/MB/MC DT$_FW_DEFPA V6.1 SYS$FWDRIVER.EXE 
DETRA DT$_IC_DETRA V6.1 SYS$ICDRIVER.EXE 
DW300 DT$_IR_DW300 V6.1 SYS$IRDRIVER.EXE 
DW110 DT$_IR_DW300 V6.2 SYS$IRDRIVER.EXE 
TC4048 DT$_IW_TI380PCI V6.2 SYS$IWDRIVER.EXE 
M8154 DT$_IW_TI380PCI V7.1 SYS$IWDRIVER.EXE 
DGLTA DT$_HC_OTTO V7.1-1H1 SYS$HCDRIVER.EXE 
DGLPB DT$_HW_OTTO V7.1-1H1 SYS$HWDRIVER.EXE 
DGLPA-FA DT$_HW_METEOR V7.1-1H1 SYS$ATMWORKS351.EXE 
DAPBA-UA DT$_HW_HE155 V7.1-1H1 SYS$HWDRIVER4.EXE 
DAPBA-FA DT$_HW_HE155 V7.1-1H1 SYS$HWDRIVER4.EXE 
DAPBA-UA DT$_HW_HE155 V7.1-1H1 SYS$HWDRIVER4.EXE 
DAPCA-FA DT$_HW_HE622 V7.1-1H1 SYS$HWDRIVER4.EXE 

NOTE PMAD is a single LANCE device. 


DELTA is a dual LANCE device. 
DE486 is a quad Tulip device. 
DE504 is a quad DE500 device. 
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DE602-AA,TA,BA,BB are dual Intel 8255x devices. A daughter card, DE602-TA or -FA, can be 
installed for additional ports. 

Trifecta is a combo device made by Intraserver. 

The Galaxy Shared Memory driver, SYS$EBDRIVER.EXE, emulates an Ethernet device 
supporting jumbo frames. 

LOM, LAN on Motherboard, is a LAN device embedded on the system board. 
10Base2 is also known as BNC or Thinwire. 

10Base5 is also known as AUI or Thickwire. 

100BaseTX devices can do 10BaseT as well. 

1000BaseTX devices can do 10BaseT and 100BaseTX as well. 

1000BaseSX is 1000 megabits/second multimode fiber. 

100 mmf is 100 megabits/second multimode fiber. 

SAS in an FDDI Single-Attached Station. 

DAS in an FDDI Dual-Attached Station. 

DEFPA-xC is required for 3.3 volt (only) PCI. 

4/16 STP/UTP is 4 or 16 megabits/second with STP or UTP cabling. 

M8154 is a TC4048 equivalent made by Racore Networks. 

Token Ring is not supported on EV6-based or later systems. 

EL is the emulated LAN device associated with the parent ATM device. 

155 mmf is OC3 multimode fiber. 

622 mmf is OC12 multimode fiber. 


9.2.3 OpenVMS 164 LAN Devices 


Table 9-5 and Table 9-6 show the LAN devices supported by the OpenVMS I64 operating system. Table 9-6 
lists additional information for the devices listed in Table 9-5. Most of the LAN devices are described here, but 
refer to the Software Product Description for the OpenVMS Operating System (SPD 82.35.xx) for the 
definitive list of supported devices. 


Table 9-5 Supported OpenVMS I64 Systems LAN Devices, Part 1 
Medium Medium Type I/O Bus pales i Scat sii creas 
Ethernet 100Base TX PCI A5230A EW EWA DT$_EW_DE500 
Ethernet 4x100BaseTX PCI A5506B EW EWA DT$_EW_DE500 
Ethernet 100BaseTX PCI 82559 (LOM) EW EWA DT$_EI_82559 
Ethernet 1000BaseSX PCI A6847A EW EWA DT$_EW_BCM5701 
Ethernet 1000BaseTX PCI A6825A EW EWA DT$_EW_BCM5701 
Ethernet 2x1000BaseSX PCI-X A7011A EI EIA DT$_EI_82540 
Ethernet 2x1000BaseTX PCI-X A7012A EI EIA DT$_EI_82540 
Ethernet 1000BaseTX PCI-X Intel 82546 EI EIA DT$_EI_82540 
(LOM) 

Ethernet 1000BaseSX PCI-X AB352A EW EWA DT$_EW_BCM5703 
Ethernet 1000BaseSX PCI-X A9782A EW EWA DT$_EW_BCM5703 
Ethernet 1000BaseTX PCI-X A9784A EW EWA DT$_EW_BCM5703 
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Table 9-5 Supported OpenVMS I64 Systems LAN Devices, Part 1 (Continued) 
Medium Medium Type I/O Bus tli i gee ee a 
Ethernet 1000BaseTX PCI-X AB290A EW EWA DT$_ EW_BCM5703 
Ethernet 2x1000BaseTX PCI-X AB465A EW EWA DT$_EW_BCM5704 
Ethernet 1000Base TX PCI BCM5701 EW EWA DT$_EW_BCM5701 

(LOM) 
Table 9-6 Supported OpenVMS I64 Systems LAN Devices, Part 2 
Device i a Driver Name 
A5230A DT$_EW_DE500 V8.2 SYS$EWDRIVER_DE500BA.EXE 
A5506B DT$_EW_DE500 V8.2 SYS$EWDRIVER_DE500BA.EXE 
82559 (LOM) DT$_EI_ 82559 V8.2 SYS$EIDRIVER.EXE 
A6847A DT$_EW_BCM5701 —‘V8.2 SYS$EW5700.EXE 
A6825A DT$_EW_BCM5701 —‘V8.2 SYS$EW5700.EXE 
A7011A DT$_EI_ 82540 V8.2 SYS$EI1000.EXE 
A7012A DT$_EI_ 82540 V8.2 SYS$EI1000.EXE 
Intel 82546 (LOM) DT$_EI_82540 V8.2 SYS$_E11000.EXE 
AB352A DT$_EI_82540 V8.2 SYS$EI1000.EXE 
A9782A DT$_EW_BCM5703 _—‘V8..2 SYS$EW5700.EXE 
A9784A DT$_EW_BCM5703 _—‘V8.2 SYS$EW5700.EXE 
AB290A DT$_EW_BCM5703_—-V8.2 SYS$EW5700.EXE 
AB465A DT$_EW_BCM5703 _—-V8.2 SYS$EW5700.EXE 
BCM5701 (LOM) DT$_EW_BCM5701 =—~‘V8.2 SYS$EW5700.EXE 
NOTE A5230A is a DE500-BA equivalent made by Adaptec. 


A5506B is a DE504-BA equivalent made by IntraServer. 

A9782A and A9784A are combo Qlogic FibreChannel plus Gigabit Ethernet devices. 
AB465A is a combo dual Qlogic FibreChannel plus dual Gigabit Ethernet device. 
BCM5701 is embedded on the RX2600 system. 

Intel 82546 is embedded on the RX1620 system. 

100BaseTX devices can do 10BaseT as well. 

1000BaseTX devices can do 10BaseT and 100BaseTX as well. 

1000BaseSX is 1000 megabits/second multimode fiber. 
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9.3 Supported Industry Standards 


Ethernet drivers support the following features and standards: 

e Ethernet and IEEE 802.3 packet format 

e Physical layer identified as 10Base5 (ThickWire), 10Base2 (ThinWire), and 10BaseT (twisted pair) 
e Fast Ethernet physical layer identified as type 100BaseTX 


e Gigabit Ethernet's physical layer is identified as 1000BaseT for unshielded twisted pair (UTP), 
1000Base-SX for multimode fiber-optic cables. 


e Gigabit Ethernet implementation of jumbo frames, a defacto industry standard using a maximum frame 
size larger than the standard Ethernet maximum of 1518 bytes. 


FDDI drivers support the following features and standards: 

e FDDI packet format 

e Transmission and reception of frame control (FC) priority 

e ANSI X3.139-1987 FDDI Media Access Control (MAC) 

e ANSI X3.148-1988 FDDI Physical Layer Protocol (PHY) 

e ANSI X3.166-1990 FDDI Physical Layer Medium Dependent (PMD) 
Token Ring drivers support the following features and standards: 

e JEKEE 802.5 packet format 

e Transmission and reception of priority bits in the access control (AC) field and the frame control (FC) field 
e Transmission of source routing header information. 

e Reception of route information (RI). 

ATM drivers over ELAN support the following features and standards: 
e Ethernet and IEEE 802.3 packet format 

e UNI Version 3.0 or 3.1 signaling protocol 

e LAN emulation (LANE) Version 1.0 

e Maximum frame sizes of 1516, 4544, and 9234 bytes 

All LAN drivers support the following features: 

e 802.2 packet format 


e JEEE 802.2 Class I service including the unnumbered information (UI), exchange identification (XID) 
commands and responses, and TEST commands and responses 


e JEEE 802.2 Class II service may be specified where the functions are provided by the user application 


e Six-byte destination and source address fields 
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9.4 LAN I/O Architecture 


The OpenVMS LAN software employs a class/port driver architecture to allow LAN applications to 
communicate with other nodes over the LAN device and the network. 


The class driver is implemented by a collection of execlets known as the LAN common routines. The LAN 
common routines implement two APIs, QIO and VCI. LAN applications interface to the LAN device port 
drivers using these APIs in a common manner across each type of LAN (Ethernet, FDDI, Token Ring, ATM, 
and Shared Memory). An execlet for each LAN medium minimizes the differences between them so 
applications can operate transparently over different types of LANs. LAN over ATM emulates Ethernet and 
uses the Ethernet LAN common routines. ATM needs a significant amount of additional support code to 
provide LAN emulation (LANE) and Classical IP (CLIP) support. This support code is located in an ATM 
execlet. LAN over Shared Memory also emulates Ethernet and uses the Ethernet LAN common routines. No 
additional support code is needed for Shared Memory. 


The port drivers operate the LAN hardware, and there is one port driver for each type of LAN device. Many 
of the port drivers operate multiple variations of similar hardware. One port driver for ATM emulates 
Ethernet and another emulates IP (called Classical IP). The port driver for Shared Memory emulates 
Ethernet. Unlike the port drivers that directly control LAN hardware, the emulated port drivers are pseudo 
drivers that implement a pseudo hardware interface in software. 


When coorelated to the OSI Model, the LAN implementation occupies the bottom two layers, the LAN 
common routines and LAN port drivers constitute the Data Link Layer, and the LAN device hardware the 
Physical Layer and parts of the Data Link Layer. The LAN drivers are often called the data link drivers. 


9.4.1 LAN Data Structures 


The OpenVMS I/O subsystem describes devices in terms of a Unit Control Block (UCB). There is a UCB for 
each device, which may be an actual physical device or a pseudo or virtual device. LAN devices include 
physical devices, NICs located in PCI buses, for example; and virtual devices, a shared memory emulated 
Ethernet device or an ATM emulated LAN device. The LAN drivers define an extension to the standard VMS 
UCB that includes additional fields needed to provide LAN context. 


When a LAN application wants to use a LAN device, it assigns a channel (opens a port) to the UCB associated 
with the LAN device. When this occurs, the VMS I/O subsystem makes a copy of the device UCB and 
associates the channel with this cloned UCB. Then the application can activate the channel by specifying the 
desired characteristics of the channel, such as protocol type and what multicast addresses to enable. The unit 
0 UCB is called the template UCB. Each non-zero UCB represents a channel to the device and contains 
application-specific channel characteristics. 


Each LAN driver also maintains another structure, the LAN Station Block (LSB), which contains LAN 
common information as well as device-specific data. For each LAN device there is one LSB and a 
cooresponding unit 0 UCB. The LSB contains device-specific data the would be inappropriate to include in 
the UCB structures such as device rings and device counters. 


In summary, the UCBs contain application-specific data. The LSBs contain device and driver-specific data. 
There is one LSB and one template UCB per LAN device that are created and initialized during device 
discovery. Whenever an application opens a channel to a particular LAN device, the template UCB is cloned 
to a newly created cloned UCB which represents the channel. There is one cloned UCB for each channel. 
When the channel is deassigned, the cloned UCB ceases to exist along with any context associated with the 
channel. 


Additional data structures are defined to allow applications to send and receive I/O requests to the LAN 
drivers, as described in the following QIO and VCI sections. 
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9.4.2 Hardware Configuration 


When the system boots, system support code probes the I/O buses looking for I/O devices. On VAX systems, 
this code probes Unibus, QBUS, BI, XMI, and TURBOchannel buses and identifies I/O devices and loads the 
drivers needed for each device. On Alpha and 164 systems, device configuration is done by comparing device 
IDs found during bus probing with entries in the file SYS$SYSTEM:SYS$CONFIG.DAT. This file includes 
the set of supported LAN devices on Alpha and I64 systems, as well as entries for other I/O devices upported 
such as SCSI, FibreChannel, USB, ATA and others. 
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9.4.3 Software Modules 


OpenVMS LAN software consists of the LAN common routines, LAN port drivers, the LAN Control Programs, 
and LAN diagnostic software listed in Table 9-7. 


SYS$LOADABLE_IMAGES 


SYS$LOADABLE_IMAGES 


SYS$SYSTEM 


SYS$SYSTEM 


SYS$SYSTEM 


SYS$LIBRARY 


SYS$LIBRARY 


SYS$LIBRARY 


SYS$LOADABLE_IMAGES 


NET$CSMACD.EXE 


NET$FDDI.EXE 


SYS$CONFIG.DAT 


LANCP.EXE 


LANACP.EXE 


SDA. EXE 


SDA$SHARE.EXE 


LAN$SDA.EXE 


LAN port drivers 


VAX, Alpha, 164 


VAX, Alpha 


Alpha, I64 


VAX, Alpha, 164 


VAX, Alpha, 164 


VAX 


Alpha, 164 


Alpha, 164 


VAX, Alpha, 164 


Table 9-7 LAN Software Module 
Location Module Architecure Function 

SYS$LOADABLE_ IMAGES SYS$LAN.EXE Alpha, 164 LAN common routines, 
common across all 
media types 

SYS$LOADABLE IMAGES SYS$LAN_ CSMACD.EXE Alpha, 164 LAN common routines, 
Ethernet-specific 
support 

SYS$LOADABLE_ IMAGES SYS$LAN_FDDI.EXE Alpha LAN common routines, 
FDDI-specific support 

SYS$LOADABLE IMAGES SYS$LAN_TR.EXE Alpha LAN common routines, 
Token ring-specific 
support 

SYS$LOADABLE IMAGES SYS$LAN_ATM.EXE Alpha LAN common routines, 


ATM-specific support 


DECnet-Plus network 
management support 
routines for Ethernet 


DECnet-Plus network 
management support 
routines for FDDI 


Device ID entries for 
file-based device 
configuration 


LAN Control Program 


LAN Auxiliary Control 
Program, including 
MOP server 


System Dump Analyzer 
or System Analyzer 


System Dump Analyzer 
or System Analyzer 


SDA extension for LAN 
drivers 


LAN port drivers 
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The NET$ modules are only loaded when DECnet-Plus is configured on the system. SYS$CONFIG.DAT 
includes LAN devices as well as any other I/O devices. LAN support represents only a small portion of the 
SDA.EXE and SDA$SHARE.EXE images. 


On VAX, the LAN common routines are linked with the LAN port drivers as part of each driver image. On 
Alpha and I64, these routines are separate execlets. 


9.4.4 Application APIs 


The LAN common routines provide two APIs to allow applications to interface to the LAN drivers and 
ultimately to send and receive data over the network. The APIs allow an application to initialize a port 
(assign a channel), send a packet over the port, receive a packet from the port, and do other management 
functions such as set port parameters, obtain port parameters and counters, and to shut down the port 
(deassign the channel). 


The APIs are: 


e QIO — An unprivileged interface to the LAN drivers, designed for user mode code. 
e VCI— A privileged interface to the LAN drivers that runs in kernel mode at IPL 8, designed to be very 
efficient. 


9.4.4.1 QIO API 


The QIO API is implemented in the LAN common routines to interface between an application and the LAN 
port driver in user mode. The QIO subsystem passes I/O requests from the application to the LAN driver. 
The LAN driver performs the requested I/O and returns status and data to the application. 


An application calls SYS$QIO with a function code, function modifiers, and addresses of buffers that provide 
any information needed, such as a buffer containing transmit data, transmit header data, a buffer to contain 
receive data and receive header data, and buffers for setmode and sensemode functions. This information is 
passed to the LAN driver via the P1-P6 QIO parameters. 


The LAN common routines translate the I/O function in the QIO request to a transmit, receive, sensemode, 
setmode, or diagnose operation that is passed on the LAN port driver. 


The LAN port driver does the transmit request, retrieves the receive packet, collects sensemode data, sets 
characteristics, or does the diagnose function, and passes the results back through the LAN common routines, 
back through the QIO subsystem, and back to the application. 


QIO operations do buffered I/O. This, in addition to considerable validation of the QIO request, makes for a 
robust user mode interface, but less efficient from a performance standpoint than the VCI interface. 


9.4.4.1.1 QIO Program Operation The following sequence shows a typical application sequence, to start 
a port, do transmits and receives, then shut down a port: 


1. Use the Assign I/O Channel ($ASSIGN) system service to assign I/O channels to one or more of the LAN 
device names and devices specified in Table 9-1 through Table 9-6. $ASSIGN creates a new unit control 
block (UCB), to which the channel for the port is assigned. 


2. Start up the port with the set mode function and startup function modifier (see Section 9.7.3.1. You must 
supply the required P2 buffer parameters listed in Table 9-39. 


3. Perform read, write, and sense mode operations as needed. 
4. Shut down the port with the set mode function and shutdown function modifier (see Section 9.7.4. 


5. Use the Deassign I/O Channel ($DASSGN) system service to deassign the I/O channel. 


The sample programs described in ?-*Section 9.8.2 illustrate a QIO implementation. 
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9.4.4.2 VCI API 


The VCI API is implemented in the LAN common routines to interface between the application and the LAN 
port driver in kernel mode at IPL 8. The VCI application calls VCI routines in kernel mode at IPL 8. The VCI 
routines are part of the LAN common routines. There are routines to initiate a port management request (to 
start, stop, and change a port) and to initiate a transmit request. The VCI application provides routines that 
the LAN common routines calls for transmit, receive, and port management completion. 


An applications calls a VCI initiation routine with an I/O request that contains the transmit buffer or 
pointers to the transmit data, or the port management buffer data. 


The LAN common routines process the transmit or port management request and passes the request on to the 
LAN port driver. 


The LAN port driver does the transmit request, or sets characteristics, and passes the results back through 
the LAN common routines, and back to the VCI application by calling the application's completion routine. 
When a receive packet arrives, the LAN common routines passes the receive buffer to the VCI application by 
calling the application's receive completion routine. When the application has completed processing the 
receive data, it returns the receive buffer to the LAN common routines by calling a return receive buffer 
routine. 


VCI operations do direct I/O, avoiding buffer copies in most cases. VCI applications are considered trusted 
applications, so must abide by the VCI specification to gain that trust and to ensure system integrity is 
maintained operating in kernel mode with privileges. 


9.4.5 LAN Addressing 


Each LAN device is identified by a hardware address that is intended to uniquely identify the LAN device and 
local system as a node on the network. The hardware address is a 48-bit address known as a MAC address or 
Ethernet address. 


Ethernet addresses are represented by the Ethernet standard as six pairs of hexadecimal digits (six bytes), 
separated by hyphens (for example, AA-01-23-45-67-FF). The bytes are displayed from left to right in the 
order in which they are transmitted; bits within each byte are transmitted from right to left. In this example, 
byte AA is transmitted first; byte FF is transmitted last. (See the description of NUA$C_PCLI_PHA in 
Table 9-39, Section 9.7.3.1, for the internal representation of addresses.) 


For Token Ring networks, the address is often given in bit-reversed form, called canonical format, separated 
by colons. For example, AA-01-23-45-67-FF in canonical format is 55:80:C4:A2:E6:FF. 


Upon application, IEEE assigns a block of addresses to a producer of LAN nodes. Thus, every manufacturer 
has a unique set of addresses to use. Normally, one address out of the assigned block of physical addresses is 


permanently associated with each device (usually in read-only memory). This address is known as the 
hardware address or MAC address of the device. Each individual device has a unique hardware address. 


9.4.5.1 Ethernet Address Classifications 


An Ethernet address can be a physical address of a single node or a multicast address, depending on the value 
of the low-order bit of the first byte of the address (this bit is transmitted first). Following are the two types of 
node addresses: 


e Physical address—The unique address of a single node on a LAN. The least significant bit of the first byte 
of a physical address is 0. (For example, in physical address AA-00-03-00-FC-00, byte AA in binary is 1010 
1010, and the value of the low-order bit is 0.) This is also called an individual address. 
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e Multicast address—A multidestination address of one or more nodes on a given LAN. The least 
significant bit of the first byte of a multicast address is 1. (For example, in the multicast address 
OB-22-22-22-22-22, byte OB in binary is 0000 1011, and the value of the low-order bit is 1. This is the first 
bit of the address as transmitted over the wire.) 


9.4.5.2 Selecting an Ethernet Physical Address 


The OpenVMS interface to the LAN controllers allows you to set a physical address of the controller. The 
selection of the physical address of a LAN controller is different for Ethernet and FDDI. 


For Ethernet, all users of the controller must agree on this address. The first user of the controller chooses the 
physical address; any additional users of the controller must specify either the same physical address, no 
physical address, or change the address (if allowed). When all channels to the controller are shut down, the 
next user to start a channel chooses the physical address. The controller's physical address is always chosen 
on the first successful startup when there are no active ports. If the address is not chosen at this time, the 
controller's hardware address is used as the physical address. 


For Ethernet, the Can Change Address parameter allows the physical address to be changed even though 
there are active users. If all current users of the controller have set the NUA$C_PCLI_CCA parameter to 
NMA$C_STATE_ON, then the physical address can be changed. 


For FDDI, each port using a controller may specify its own unique physical address. Any combination of 
sharing of physical addresses is also allowed across the ports of an FDDI controller. For example, ports A, B, 
and C may use one unique physical address and ports D and E may use another unique address. 


9.4.5.3 Ethernet Physical and Multicast Address Values 


The following shows the multicast addresses assigned for use in cross-company communications:. 


Value Meaning 
FF-FF-FF-FF-FF-FF Broadcast 
CF-00-00-00-00-00 Loopback assistance 


The following lists the commonly used multicast addresses. 


Value Meaning 
AB-00-00-01-00-00 Dump/load assistance 
AB-00-00-02-00-00 Remote console 
AB-00-00-03-00-00 Level 1 and Level 2 routers 
AB-00-00-04-00-00 All end nodes 
09-00-2B-02-00-00 Level 2 routers 
AB-00-00-05-00-00 Reserved for future use 
through 
AB-00-03-FF-FF-FF 
AB-00-03-00-00-00 LAT 
AB-00-04-00-00-00 For use by HP customers for their own applications 
through 


AB-00-04-00-FF-FF 
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Value Meaning 


AB-00-04-01-00-00 
through 
AB-00-04-01-FF-FF 


Local area VMScluster 


AB-00-04-02-00-00 
through 
AB-00-04-FF-FF-FF 


Reserved for future use 


09-00-2B-01-00-00 Bridge management 


09-00-2B-01-00-01 Bridge hello multicast 


9.4.5.4 Token Ring Functional Address Mapping 


Except for the global broadcast address (FF-FF-FF-FF-FF-FF), Token Ring hardware does not support the 
802 standard group LAN address mechanism. Instead, it uses functional addresses. Functional addresses 
are locally administered group addresses (multicast addresses). The first two bytes of the address are always 
03-00 (canonical format), and the remaining four bytes contain a bit mask that specifies which of the 32 
possible combination masks is being described. 


Because most OpenVMS LAN applications use standard multicast addresses, a mechanism has been 
designed to map functional addresses to globally and locally administered multicast addresses. This allows 
applications to use the same multicast addresses that are used in the other LAN media. 


Table 9-8 shows the default mapping used by the OpenVMS Alpha Token Ring drivers: 


Table 9-8 


Address Mappings of Token Ring Drivers 


Multicast Address 


Functional 
Address 


Bit-Reversed 


Description 


09-00-2B-00-00-04 


09-00-2B-00-00-05 


CF-00-00-00-00-00 
AB-00-00-01-00-00 
AB-00-00-02-00-00 
AB-00-00-03-00-00 
09-00-2B-02-00-00 
09-00-2B-02-01-0A 


AB-00-00-04-00-00 
09-00-2B-02-01-0B 
09-00-2B-00-00-07 
09-00-2B-00-00-0F 


03-00-00-00-02-00 


03-00-00-00-01-00 


03-00-00-08-00-00 
03-00-02-00-00-00 
03-00-04-00-00-00 
03-00-08-00-00-00 
03-00-08-00-00-00 
03-00-08-00-00-00 


03-00-10-00-00-00 
03-00-10-00-00-00 
03-00-20-00-00-00 
03-00-40-00-00-00 


C0:00:00:00:40:00 


C0:00:00:00:80:00 


C0:00:00:10:00:00 
C0:00:40:00:00:00 
C0:00:20:00:00:00 
C0:00:10:00:00:00 
C0:00:10:00:00:00 
C0:00:10:00:00:00 


C0:00:08:00:00:00 
C0:00:08:00:00:00 
C0:00:04:00:00:00 
C0:00:02:00:00:00 


ISO 9542 All End-system Network 
Entites 


ISO 9542 All Intermediate System 
Network Entities 


Loopback Assistance 
MOP Dump/Load 
MOP Remote Console 
DNA LI Routers 
DNA L2 Routers 


DECnet Phase IV — TRN — All 
Phase IV — TRN Routers 


DNA End nodes 

Phase IV Prime Unknown 
PCSA NETBIOS Emulation 
Local Area Transport (LAT) 
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Table 9-8 Address Mappings of Token Ring Drivers (Continued) 
Multicast Address Buncional Bit-Reversed Description 
Address 


09-00-2B-02-01-04 


09-00-2B-02-01-07 


09-00-2B-04-00-00 
09-00-2B-02-01-00 


09-00-2B-02-01-01 
09-00-2B-02-01-02 
03-00-00-00-00-01 


03-00-80-00-00-00 


03-00-00-02-00-00 


03-00-00-04-00-00 
03-00-00-00-08-00 


03-00-00-00-10-00 
03-00-00-00-20-00 
03-00-00-00-00-01 


C0:00:01:00:00:00 


C0:00:00:40:00:00 


C0:00:00:20:00:00 
C0:00:00:00:10:00 


C0:00:00:00:08:00 
C0:00:00:00:04:00 
C0:00:00:00:00:80 


LAT Directory Service Solicit (to 
slave) 


LAT Directory Service Solicit — X 
Service Class 


LAST 


DNA Naming Service 
Advertisement 


DNA Naming Service Solicitation 
DNA Time Service 
NETBUI Emulation 


If an application needs to change or add mappings, QIOs exist for performing such operations. If the system 
or network manager has a requirement regarding mapping of the functional addresses, the LAN control 
program (LANCP) utility may be used to manage the mapping. The following example maps the multicast 
address AB-01-01-01-02-03 to functional address 03-00-00-01-00-00 on Token Ring device ICAO:. 


$ MCR LANCP 


LANCP>SET DEVIC 


_LANCP> (MULTICAST=A 


_LANCP> FUNCTIONAL=00-01-00-00) 


E/MAP= —- 


ICAO: 


B-01-01-01-02-03,- 


Note that it is possible for more than one multicast address to map to the same functional address. In all 
cases, the use of the functional address is associated with an individual application's protocol. 


9.4.6 LAN Frame Formats 


Several different LAN physical layer protocols are supported by OpenVMS with some differences in frame 
formats. The following sections describe the similarities and differences in these frame formats. Despite 

differences, the QIO interface to the LAN drivers is designed to allow applications to run over the different 
media with few changes to the application. 
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The frame formats available in the LAN media are shown in Figure 9-1. 


Figure 9-1 LAN Frame Formats 


Ethernet with Ethernet header 


Ethernet Header DATA CRC 


Ethernet with 802.3 header 


802.3 Header 802.2/802.1 Header DATA CRC 


FDDI 


FDDI Header 802.2/802.1 Header DATA CRC 


Token Ring 


Token Ring Header} 802.2/802.1 Header DATA CRC 


ATM ELAN with Ethernet Header 


LEH Ethernet Header DATA 


ATM ELAN with 802.3 Header 


LEH 802.3 Header 802.2/802.1 Header DATA 


CRC: Cyclic Redundancy Check 
LEH: LAN Emulation Header 


ZK-3901A-Al 


Note that Ethernet provides two frame formats and the FDDI provides one frame format. The 802.1 header is 
an optional extension to the 802.2 header. 


9.4.6.1 Ethernet Frames 
There are two headers for Ethernet frames: 


e Ethernet header 
e JEEE 802.3 header 
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Figure 9-2 illustrates an Ethernet frame with an Ethernet header. 


Figure 9-2 Ethernet Frame with Ethernet Header 


6 6 


2 46=>1500 4 


Minimum total length — 64 bytes 
Maximum total length —1518 bytes 

DA: Destination Address 

SA: — Source Address 

PTY: Ethernet Protocol Type 

DATA: User’s data (can include 2byte length field) 


CRC: Cyclic Redundancy Check 
ZK3743AGE 


The Ethernet header consists of the DA, SA, and PTY fields. Ethernet frames must be at least 64 bytes in 
length, which means that the minimum data length is 46 bytes. Applications select Ethernet format by 
specifying NMA$C_LINFM_ETH (the default) as the value for NNMA$C_PCLI_FMT in their P2 
characteristics buffer. If the amount of actual data to be transmitted is less than 46 bytes, the Ethenet drivers 
transmit extra bytes of zero after the application data. 


Figure 9-3 illustrates a Ethernet frame with an IEEE 802.3 header. 


Figure 9-3 Ethernet Frame with IEEE 802.3 Header 


6 6 2 46=>1500 4 
DA: Destination Address 
SA: Source Address 


LEN: — The length of data portion only. It can 
be less than 46 if the user supplied less than 
46 bytes of data, but the frame is then 
padded to meet minimum length requirements. 


DATA: User's data 
CRC: Cyclic Redundancy Check 


ZK3745AGE 


The IEEE 802.3 format is similar to the Ethernet format, except the PTY field is replaced by the LEN field. 
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9.4.6.2 FDDI Frames 
Figure 9-4 illustrates the format of FDDI frames. 


Figure 9-4 FDDI Frame Format 


6 6 


1 0=>4478 4 


FC: Frame Control contains a “priority” field that 
can be used to determine if the frame originated 
on the FDDI or on the Ethernet. 


DA: Destination Address 
SA: Source Address 


DATA: User’s data 


CRC: Cyclic Redundancy Check 
ZK3742AGE 


The FDDI header consists of the FC, DA, and SA fields. 


9.4.6.3 Token Ring Frames 
Figure 9-5 illustrates the format of Token Ring frames. 


Figure 9-5 Token Ring Frame Format 


Ac|Fc|pa| sa] [RI | DATA | CRC 


1 1 #6 6 O30 O=>4476 4 


AC: Access Control contains priority for the frame. 
FC: Frame Control contains the type of frame. 
DA: Destination Address 
SA: Source Address 
RI: Optional Routing Information. Only valid with 
packets that are source routed. 
DATA: User's data 
CRC: Cyclic Redundancy Check 


ZK6679AGE 
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9.4.6.4 ATM ELAN Frames 


Figure 9-6 illustrates the format of LAN emulation data frame format for the IEEE 802.3 and Ethernet 
Header. 


Figure 9-6 LAN Emulation Data Frame Format with IEEE 802.3/Ethernet Header 


fies om [sa [eran] oar 
2 6 6 2 


46=>* 


“4500 For an 802.3 LAN emulation of size 1516 
4528 For an 802.3 LAN emulation of size 4544 
9218 For an 802.3 LAN emulation of size 9234 


LEH: LAN Emulation Header 
DA: Destination Address 
SA: Source Address 


PTY/LEN: For frames with the IEEE 802.3 header, 
PTY is the Ethenet Protocol Type. For 
frames with the Ethernet header, LEN is 
the length of the data portion only. It can 
be less than 46 if the user supplied less than 
46 bytes of data, but the frame is then 
padded to meet minimum requirements. 


DATA: User’s data 


ZK8990AGE 


9.4.6.5 Ethernet (Ethernet Version 2, DIX) Frame Format 


The Ethernet format specifies a two-byte protocol type field followed by an optional length field. The length 
field is included in transmit packets and expected in receive packets with the PAD parameter is enabled. The 
following sections describe these features. 


9.4.6.5.1 Ethernet Protocol Types Every Ethernet frame has a 2-byte protocol type field. This field is 
used to determine the port to which a packet belongs. When an application starts a port, it specifies the 
protocol type to be used on that port. Packets sent over that port always have the protocol type inserted in the 
packet header by the LAN driver, and packets received for that protocol type are delivered to the application 
that owns the port. Valid protocol types are in the range 05-DD through FF-FF. 


The following lists the cross-company protocol types: 


Value Meaning 
08-00 IP protocol 
08-06 Address resolution protocol (ARP) 
86-DD IP protocol Version 6 (IPV6) 
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Value Meaning 


90-00 Ethernet Loopback protocol 


The following list some commonly used protocol types. 


Value Meaning 
60-01 DNA Dump/load (MOP) 
60-02 DNA Remote Console (MOP) 
60-03 DNA Routing 
60-04 Local Area Transport (LAT) 
60-05 Diagnostics 
60-06 Customer use 
60-07 System Communication Architecture (SCA) 
80-38 Bridge 
80-3C DNA Naming Service 
80-3D CSMA/CD Encryption 
80-3E DNA Time Service 
80-3F LAN Traffic Monitor 
80-40 NETBIOS Emulator (PCSG) 
80-41 Local Area System Transport (LAST) 


9.4.6.6 802 (IEEE 802.x LLC) Frame Format 


The IEEE 802 packet formats accepted for a port depend on the service enabled on that port. All 802 packet 
formats have an 802.2 header. The service on the port determines the valid values for the 802.2 fields. 


When a port is started, the NUA$C_PCLI_SRV parameter in the P2 buffer selects the service on that port. A 
value of NMA$C_LINSR_CLI specifies Class I service and a value of NUA$C_LINSR_USR specifies 
er-supplied service (the default). 


9.4.6.6.1 802 Service Access Point (SAP) Types Every IEEE 802 frame has a 1-byte Service Access 
Point (SAP) field. This field identifies where the packet came from, the source port on the sending node. And 
it identifies the destination port for the packet on the receiving node. When an application starts a port, it 
specifies the SAP value that will identify the port. Packets sent over that port always have SAP value 
inserted into the SSAP field in the packet header by the LAN driver, and packets received for the SAP value 
in the DSAP field are delivered to tha application that owns the port. Also, when transmitting a packet, the 
application specifies the destination SAP value, in addition to the destination address. And when receiving a 
packet, the application is given the source SAP value as well as the source address. 
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The following lists some commonly used SAP values. 


Value Meaning 
FE DECnet-V Link State Routing 
FO Pathworks 


9.4.6.6.2 Class I Service Packet Format For Class I service, only three packet formats are transmitted 
and received: UI, XID, and TEST. Figure 9-7 shows the 802.2 header format for Class I service. 


Figure 9-7 Class I Service 802.2 Header 
Size of 
Field 
(Bytes) 
1 
1 
1 
ZK4798GE 


The control field for an 802 packet is always an unnumbered control field. The unnumbered control field, 
which is always 1 byte in length, is passed by the P4 argument of the write QIO and can be one of the 
following binary values: 


¢ UI command (00000011) 


This is the unnumbered information command. It is the method used to transmit data from one user to 
another and is the most widely used control field value. 


The UI command can be specified by using NMA$C_CTLVL_UI. 
e XID command (101p1111) 


This is the exchange identification command. It is used to convey information about the port. The “p” bit 
is the poll bit and can be either 0 or 1. This command can be specified by using NMA$C_CTLVL_XID for a 
“0” poll bit or NUA$C_CTLVL_XID_P for a “1” poll bit. 


e XID response (101f1111) 


The XID response is a response to an XID command. The “f” bit is the final bit and will match the poll bit 
from the XID command. 


e TEST command (111p0011) 


The TEST command is used to test a connection. The “p” bit is the poll bit and can be either 0 or 1. This 
command can be specified by using NUA$C_CTLVL_TEST for a “0” poll bit or NMA$C_CTLVL_TEST_P 
for a “1” poll bit. 


e TEST response (111f0011) 


The TEST response is a response to a TEST command. The “f” bit is the final bit and will match the poll 
bit from the TEST command. 
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An 802 format port with Class I service is allowed to transmit UI, XID, and TEST commands. An 802 format 
port with Class I service is allowed to receive UI commands and XID and TEST responses. 


Refer to the IEEE 802.2 Standard for more information on these control field values and response messages. 


9.4.6.6.3  User-Supplied Service Packet Format The user provides the control field values, which are 
documented in the IEEE 802.2 Standard. The user-supplied packet format is the generic packet format as 
specified in the IEEE 802.2 Standard. Class I packets (see Section 9.4.6.6.2 ) are a subset of this generic 
packet format; therefore, if the control field value of the user-supplied packet is UI, XID, or TEST, the packet 
is the same as a Class I packet. Note that Class II packets, as defined in the IEEE 802.2 Standard, include the 
UI, XID, and TEST command/response formats. 


9.4.6.6.4 Service Access Point (SAP) Use and Restrictions The IEEE 802.2 Standard places 
restrictions on both user SAPs and source SAPs (SSAPs). All SAPs are 8 bits long. Figure 9-8 shows the 
format of destination SAPs (DSAPs) and SSAPs. 


Figure 9-8 DSAP and SSAP Format 
i 0 7 0 
DSAP SSAP | SSSSSSSC/R 


ZK4800GE 


Definition of the least significant bit depends on whether the SAP is a source SAP (SSAP) or a destination 
SAP (DSAP). For a DSAP field, the least significant bit distinguishes group SAPs (bit 0 = 1) from individual 
SAPs (bit 0 = 0). For an SSAP field, the least significant bit distinguishes commands (bit 0 = 0) from responses 
(bit 0 = 1). Because these two bits are located at the same bit position within the SAP field, a group SAP 
cannot be used as an SSAP. If this were allowed, a group SAP would be interpreted as an individual SAP with 
the command/response bit set to 1, thus implying a response. The IEEE 802.2 Standard reserves for its own 
definition all SAP addresses with the second least significant bit set to 1. You should use these SAP values for 
their intended purposes, as defined in the IEEE 802.2 Standard. 


Up to four group SAPs can be enabled on each 802 port. The group SAPs enabled on a controller do not have 
to be unique for each port; for example, two 802 format ports can have the same group SAP enabled. This 
allows a single packet coming into the controller to be duplicated and passed to each port on the controller 
that has the group SAP enabled—assuming the packet has a DSAP value that is a group SAP. If the received 
packet has an individual SAP for a DSAP, the packet goes to, at most, one port. 
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9.4.6.7 802 Extended (IEEE 802.x LLC/SNAP) Frame Format 
The 802E format uses the 802.2 and 802.1 headers, as shown in Figure 9-9. 


Figure 9-9 802 Extended Header 


ZK5791GE 


For an 802E packet format, the DSAP and SSAP fields are always set to the SNAP SAP (AA hex). The SNAP 
SAP value is a special SAP value reserved for 802 extended format packets. The SNAP SAP value 
distinguishes an 802 packet from an 802 extended packet. The only valid control field value for 802 extended 
packets is UI (unnumbered information). 


9.4.6.7.1 802E PID Types Every SNAP frame has a 5-byte protocol ID (PID) field. This field is used to 
determine the port to which a packet belongs. When an application starts a port, the it specifies the PID to be 
used on that port. Packets sent over that port always have the PID inserted in the packet header by the LAN 
driver, and packets received for that PID are delivered to the application that owns the port. 


The following lists the cross-company PID values. 


Value Meaning 


08-00-2B-90-00 Loopback protocol 


The following lists some commonly used PID values. 


Value Meaning 
08-00-2B-60-02 Loopback protocol 
08-00-2B-60-01 DNA Dump/load (MOP) 
08-00-2B-60-02 DNA Remote Console (MOP) 
08-00-2B-80-3C DNA Naming Service 
08-00-2B-80-3E DNA Time Service 
08-00-2B-80-48 Availability Manager (AMDS) 
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9.4.7 Packet Padding 


This section describes the PAD parameter NMA$C_PCLI_PAD, which is used only in the Ethernet packet 
format. 


All Ethernet frames must be at least 64 bytes in length. This includes the Ethernet header, the user data, and 
the CRC. If the user data, CRC, and Ethernet header together are less than 64 bytes, zero padding bytes are 
inserted between the user data and the CRC to make a 64-byte packet. This packet padding cannot be turned 
off. 


The PAD parameter directs the LAN drivers to place a data-size field in the packet between the standard 
header and the user data. If padding is on (NMA$C_STATE_ON is specified), a 2-byte length field is inserted 
after the Protocol Type field and before the user data. 


If the PAD parameter is off (NMA$C_STATE_OFF is specified), Ethernet packets have the following 
characteristics: 


e Packets transmitted are padded with null bytes as needed (CSMA/CD only). 
e Packets transmitted do not include the size field. 


e The length of user data in the packets received is always between 46 and 1500 bytes for CSMA/CD, and 0 
to 4470 for FDDI. For example, if a 10-byte packet is transmitted, it is received as 46 bytes because the 
driver cannot determine the amount of user data in the packet—only the amount of user data plus padded 
null bytes. 


If the PAD parameter is on (NMA$C_STATE_ON is specified), Ethernet packets have the following 
characteristics: 


e Packets transmitted are padded with null bytes as needed (CSMA/CD only). 
e Packets transmitted include the size field. 


e The length of user data in the packets received is always between 0 and 1498 bytes for CSMA/CD, and 0 
to 4468 bytes for FDDI. The driver uses the size field to determine the amount of user data in the packet. 
The size field is not included in the data returned to the user. 


9.4.8 Protocol Type and PID Sharing 


Protocol types and PIDs are usually nonshareable; however, an application may benefit from a shared 
protocol implementation. The protocol access parameter (NMA$C_PCLI_ACC) allows a protocol type or PID 
to be opened in either of two shareable modes: shared-default (NMA$C_ACC_SHR) and 
shared-with-destination (NMA$C_ACC_LIM). 


The LAN drivers also provide the nonshareable exclusive mode (NMA$C_ACC_EXC). (See Table 9-39.) The 
rules and requirements for using each mode are as follows: 


e The exclusive mode is the default if no access mode is supplied as a P2 buffer parameter. This mode of 
operation does not allow the protocol to be shared by other users. Any attempt to start up another protocol 
of the same type results in an error status of SS$_BADPARAM. 


e The shared-with-destination mode is a protocol type or PID/destination address pairing that allows 
multiple users to share a protocol type or PID and to communicate with a different node. 


For a given shared protocol type or PID, there can be many “shared-with-destination” users; each user 
communicates with a different destination address. Any attempt to start a port with a destination 
address that is in use results in an error status of SS$_ BADPARAM. 
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When a “shared-with-destination” user passes the set mode P2 buffer, the buffer must contain a 
destination address in the NMA$C_PCLI_DES parameter. This destination address is used as the 
destination address in all messages transmitted, and the user receives messages only from this address. 


e The shared-default mode is the default user of a shared protocol type or PID. There can be only one such 
user for each shared protocol type or PID. A “shared-default” user does not have to exist if a protocol type 
or PID is shared, but there can be no more than one such user per shared protocol type or PID. 


The “shared-default” user receives all messages for the shared protocol type or PID, but not for any of the 
“shared-with-destination” users. The “shared-default” user also receives all messages matching both the 
shared protocol type or PID and any multicast address enabled by the “shared-default” user. 


The “shared-default” user can only transmit to multicast addresses and physical addresses that are not 
enabled by any of the “shared-with-destination” users sharing the same protocol type or PID. 


If there is no “shared-default” user of a protocol type or PID, incoming messages from nodes not among 
the “shared-with-destination” users for that protocol type or PID are ignored. 


9.5 LAN Devices 


This section describes each LAN device, giving a list of device variants and device characteristics. 


Some port drivers for these devices provide additional counters and device-specific functions that are useful 
for troubleshooting purposes. This additional data is described in a text file on the system, 
SYS$HELP:LAN_COUNTERS_AND_FUNCTIONS.TXT. 


9.5.1 Driver-Specific Internal Counters 


Driver-specific internal counters consist of data maintained by a particular LAN driver that is not common 
across all LAN drivers or is not suitable for inclusion in LAN statistics and error counters. 


The LANCP command SHOW DEVICE/INTERNAL_COUNTERS displays the internal counters maintained 
by a port driver. Some counters are special debug counters. These are not displayed unless the additional 
qualifier /DEBUG is specified. Counters that are zero are not displayed unless the additional qualifier /ZERO 
is specified. 


The LAN$SDA SDA extension also displays the complete set of internal counters with the command LAN 
INTERNAL/DEVICE=devname. 


VAX LAN drivers and some Alpha and 164 LAN drivers do not provide a LANCP or LAN$SDA mechanism for 
reading these counters. For these drivers, use SDA to display the internal counters using the command 
SHOW LAN/INTERNAL/DEVICE=devname. 


The definition of these counters may change from one driver version to the next. Some counters fields 
describe device or driver information that is useful for debug of the driver but is not particularly interesting 
otherwise. This includes such fields as device register contents. The definition of these counters fields may 
be omitted from the SYS$HELP text file. 
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9.5.2 Device-Specific Functions 


The device-specific functions provice additional functionality that is useful for troubleshooting and validation 
of the port driver. These functions may change from one driver version to the next. And some functions may 
be incorporated into LANCP as a standard device command. These functions are supported on Alpha and 164 
systems only. 


9.5.3 Ethernet LAN Devices 


In general terms, Ethernet includes Fast Ethernet and Gigabit Ethernet devices. The following media types 
are used: 

e 10Base2 (thinwire or BNC) — Ethernet running over thin shielded coaxial cable, half-duplex only. 

e 10Based (thickwire or AUI) — Ethernet running over thick shielded coaxial cable, half-duplex only. 


e 10BaseT — Ethernet running over Category 5 unshielded twisted-pair cabling (UTP). It uses two of the 
four pairs of wires to provide full-duplex communication. 


e 100BaseTX — Fast Ethernet running over Category 5 unshielded twisted-pair cabling (UTP). It uses two 
of the four pairs of wires to provide full-duplex communication. 


e 100BaseFX — Fast Ethernet running over multimode optical fiber cable. It uses two strands of fiber to 
provide full-duplex communication. 


e 1000BaseT — Gigabit Ethernet running over Category 5 unshielded twisted-pair cabling (UTP). It uses 
two of the four pairs of wires to provide full-duplex communication. 


e 1000BaseSX — Gigabit Ethernet running over multimode optical fiber cable. It uses two strands of fiber 
to provide full-duplex communication. 


9.5.3.1 DEMNA Ethernet Device 


The DEMNA is an XMI bus Ethernet device that is supported on VAX and Alpha systems that have an XMI 
bus. A similar hardware design, the DEBNA, is intended for VAX systems with a BI bus. There are several 
variants of the DEBNA, the DEBNK, DEBNT, and DEBNI. Each device is implemented using a VAX chip 
and a LANCE chip. Firmware on the device runs on the VAX and operates the LANCE chip. 


Table 9-9 DEMNA Characteristics 
Device Bus Characteritics 
DEMNA XMI 10Based (thickwire) Ethernet only 
DEBNI BI 10Based (thickwire), Ethernet only 
DEBNT BI 10Based (thickwire), Ethernet + TK50 combo adapter 
DEBNK BI 10Based (thickwire), Ethernet + TK50 combo adapter 
DEBNA BI 10Based (thickwire), Ethernet + TK50 combo adapter 
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9.5.3.2 SGEC/TGEC Ethernet Devices 


The Second Generation Ethernet Controller (SGEC) is a embedded Ethernet chip (LOM) on a VAX 
workstation. The nearly identical Third Generation Ethernet Controller (TGEC) is embedded on the 
Alpha-based Digital 4000 system. 


Table 9-10 SGEC/TGEC Characteristics 
Device Bus Characteritics 
SGEC VAX 10Base2 (thinwire) 
TGEC Alpha 10Base2 (thinwire) 


9.5.3.3 LANCE Ethernet Devices 


The LANCE is a widely used Ethernet chip used on VAX and Alpha systems. It is used in in embedded (LOM) 
configurations on VAX and Alpha systems, and in QBUS and TURBOchannel-based NICs on VAX and Alpha 
systems. 


Table 9-11 LANCE Characteristics 
Device Bus Characteritics 

LANCE VAX, LOM, 10Base2 (thinwire) 
Alpha 

PMAD VAX, TURBOchannel NIC, 10Base5 (thickwire) 
Alpha 

DELTA VAX, Dual TURBOchannel, 10Base5 (thickwire) 
Alpha 

DESQA VAX QBUS NIC, 10Base2 (thinwire), 10Base5 (thickwire) 

KFE52 VAX Fault-tolerant VAX, 10Base2 (thinwire) 

DE422 Alpha EISA, 10BaseT (UTP), 10Base2 (thinwire) 

DE200 Alpha ISA, 10Base2 (thinwire), 10Based5 (thickwire) 

DE201 Alpha ISA, 10BaseT (UTP) 

DE202 Alpha ISA, 10Base2 (thinwire), 10BaseT (UTP) 


9.5.3.3.1 LANCE Hardware Configuration For implementations that include both the 10Base2 and 
10Base5d ports, a switch next to the physical connectors determines the port selection. 


The DE422 includes a jumper block on the NIC that selects 10BaseT or 10Base2. 
The DE20x NICs are configured by a 12-pin DIP switch on the NIC. See the DE20x User Guide for details. 
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9.5.3.4 DEQNA Ethernet Devices 
The DEQNA and similar NICs are used in QBUS-based VAX systems. 
Table 9-12 DEQNA Characteristics 
Device Characteritics 

DEQNA Not supported for cluster use. 10Base2 (thinwire), 10Base5 (thickwire) 

DELQA LANCE-based DEQNA replacement, 10Base2 (thinwire), 10Based (thickwire) 

DEQTA DELQA with new firmware, 10Base2 (thinwire), 10Based (thickwire) 


9.5.3.5 DEUNA Ethernet Devices 
The DEUNA and similar NICs are used in Unibus-based VAX systems. 


Table 9-13 DEUNA Characteristics 
Device Characteritics 
DEUNA 10Based (thickwire) 
DELUA DEUNA replacement, 10Based (thickwire) 


9.5.3.6 LEMAC Ethernet Devices 


The DE203 and variants are based on the LEMAC chip. These NICs are used on ISA-based Alpha 
workstations, primarily the AlphaStation 200 and 400 system. 


Table 9-14 LEMAC Characteristics 
Device Characteritics 
DE203 10Base2 (thinwire) 
DE204 10BaseT (UTP) 
DE205 10Base2 (thinwire), 10Base5 (thickwire), 10BaseT (UTP) 


9.5.3.6.1 ISA LEMAC Hardware Configuration The DE203 NIC and variants are configured by the 
console of AlphaStations 200 and 400 systems using the ‘isacfg' console utility. First, an ISA slot number is 
chosen, then the IRQ, IO base address, and DMA channel address. Then the slot is configured with the 
selected characteristics. When the system is reset or power-cycled, the console configures the device as 
specified. 


For complete information on using 'isacfg' from your console prompt, refer to the hardware documentation 
associated with your system for more information. 


The ISA slot number is any one of three available slots that is not already in use. The physical location of the 
NIC in the ISA bus is of no consequence as any free slot can be assigned to the NIC. 


To initialize the 'isacfg' data at the console prompt: 
>>> isacfg -init 
To add a DE205 in slot 1, using IRQ 15: 


>>> add_de205 
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>>>isacfg -slot 1 -dev 0 -mod -irg 15 
To display the ISA configuration data for slot 1: 


>>>isacfg -slot 1 


handle: DE200-LE 

etyp: 1 

slot: 1 

dev: 0 

enadev: 1 

totdev: 1 

iobase0: 300 iobasel: 8000000000000000 

iobase2: 8000000000000000 iobase3: 8000000000000000 
iobase4: 8000000000000000 iobase5: 8000000000000000 
membase0O: d0000 memlenO: 10000 

membasel: 8000000000000000 memlenl: 8000000000000000 
membase2: 8000000000000000 memlen2: 8000000000000000 
rombase: 8000000000000000 romlen: 8000000000000000 


dma0: 80000000 irqOd: £ 

dmal: 80000000 irgl: 80000000 
dma2: 80000000 irg2: 80000000 
dma3: 80000000 irg3: 80000000 


To display the ISA configuration at the console prompt, showing, in this example, a DE203 configured in slot 
1, and two DW110 Token Ring NICs configured in slots 2 and 3. 


>>> show config 


ISA 
Slot Device Name Type Enabled BaseAddr IRQ DMA 
0 

0 MOUSE Embedded Yes 60 12 

1 KBD Embedded Yes 60 1 

2 COM1 Embedded Yes 3£8 4 

3 COM2 Embedded Yes 2f8 3 

4 LPT1 Embedded Yes 3bc Wh 

5 FLOPPY Embedded Yes 3£0 6 2 
1 0 DE200-LE Singleport Yes 300 15 
2 0 DW11 Singleport Yes a20 10 7 
3 0 DW1l1 Singleport Yes 1a20 5 6 


9.5.3.7 3C589 Ethernet Device 


The 3COM 3C589 PCMCIA NIC is used on the Tadpole AlphaBook notebook system. There are two variants: 
Table 9-15 3C589 Characteristics 


Device Characteritics 
3C589B 10Base2 (thinwire), 10BaseT (UTP) 
3C589D 10Base2 (thinwire), 10BaseT (UTP) 
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9.5.3.8 Tulip Ethernet and Fast Ethernet Devices 


Tulip refers to an Ethernet chip designed by Digital Equipment Corporation. It also refers to later Fast 
Ethernet versions of the chip that maintain a similar programming interface, so can be controlled by the 
same driver with few changes. 


Table 9-16 Tulip Ethernet and Fast Ethernet Characteristics 
Device Bus Characteristics 
DE425 EISA 10Base2 (thinwire), 10Base5d (thickwire), 10BaseT (UTP) 
DE434 PCI 10BaseT (UTP) 
DE435 PCI 10Base2 (thinwire), 10Based5 (thickwire), 10BaseT (UTP) 
DE436 PCI Quad DE435 
DE450 PCI 10Base2 (thinwire), 10Based5 (thickwire), 10BaseT (UTP) 
DE500-XA PCI 10BaseT (UTP), 100BaseTX (UTP), auto-negotiation not supported 
DE500-AA PCI 10BaseT (UTP), 100BaseTX (UTP), auto-negotiation supported 
DE500-BA PCI 10BaseT (UTP), 100BaseTX (UTP), auto-negotiation supported 
DE500-FA PCI 100BaseFX (multimode fiber), auto-negotiation not supported 
DE504-BA PCI Quad DE500-BA 
P2SE PCI Combo SCSI + DE434 
P2SE+ PCI Combo SCSI + DE500-XA 
21142 PCI LOM, Digital Personal Workstation, all modes depending on MAU options, 
auto-negotiation supported 
21148 PCI LOM, Alpha Professional Workstation XP900/XP1000, all modes 
depending on MAU options, auto-negotiation supported 
A5230A PCI DE500-BA equivalent 
A5506B PCI DE504-BA equivalent 


9.5.3.8.1 Tulip Hardware Configuration The DE425 and DE435 contain a hardware jumper block that 
selects twisted-pair or AUI as noted on the printed circuit board. AUI includes 10Base2 (thinwire) or 10Base5 
(thickwire) and this selection is made by setting a console environment variable, by a driver autosense 
algorithm, or by a LANCP command to set the media type, speed, and duplex mode. 


On Alpha systems prior to OpenVMS Version 7.1, the Tulip driver autosenses the media connection if needed. 


On Alpha systems starting with OpenVMS Version 7.1, the Tulip driver uses the setting of a console 
environment variable to select the media connection, speed, and duplex mode. The console environment 
variable is called EWx0_MODE where x is the controller letter (for example, A, B, C, ...). The console 
environment variable is set with the command: 


SET EWx0_MODE media_selection 
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The media_selection is defined by Table 9-17. 


Table 9-17 Tulip Hardware Media Selection 
Media selection What is selected 
Twisted-pair 10BaseT (UTP) half-duplex 


Full duplex, twisted-pair 10BaseT (UTP) full-duplex 


AUI 10Base5 (thickwire) 

BNC 10Base2 (thinwire) 

Fast 100BaseTX (UTP) half-duplex 

FastFD (full duplex) 100BaseTX (UTP) full-duplex 
Autonegotiate Auto-negotiate speed and duplex (UTP) 


uring driver initialization, a message is sent to the operator's console to indicate the console selection. 


If a console environment variable has been set with an unsupported media type for the actual device, then the 
driver selects a default media type. 


An Alpha system console may assign a controller letter to an adapter differently from OpenVMS, since 
OpenVMS EW devices include Tulip, DEGPA, and Broadcom 5700, but the console only recognizes Tulip 
devices as EW devices. In this case, you can compare the MAC address listed for the device at the console 
SHOW CONFIG and the LANCP SHOW CONFIG commands. 


On 164 systems, there is no console environment variable equivalent, so the default setting is autonegotiation. 


On Alpha and I64 systems, you can override the console environment variable setting or default setting of 
auto-negotation by describing the media selection in the LANCP permanent device database. 
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9.5.3.9 Intel 82559 Fast Ethernet Devices 


82559 refers to a Fast Ethernet chip designed by Intel Corporation, either the 82558 or the 82559 chip. These 
chips are implemented on PCI bus NICs or a embedded PCI bus on the system board. Both chips support 
autonegotiation. Table 9-18 lists the Intel 82559 Fast Ethernet characteristics. 


Table 9-18 Intel 82559 Fast Ethernet Characteristics 
Device Characteristics 

DE600-AA 10BaseT (UTP), 100BaseTX (UTP) 
DE602-AA Dual DE600-AA 
DE602-BA Dual DE600-AA 
DE602-BB Dual DE600-AA 
DE602-TA Dual DE600-AA daughter card for the DE602 
DE602-FA Dual 100BaseFX (multimode fiber) daughter card for the DE602 
Trifecta Combo SCSI + DE600 
82559ER LOM, 10BaseT (UTP), 100BaseTX (UTP) 
82559 LOM, 10BaseT (UTP), 100BaseTX (UTP) 


9.5.3.9.1 82559 Hardware Configuration On Alpha systems, the 82559 driver uses the setting of a 
console environment variable to select the media connection, speed, and duplex mode. The console 
environment variable is called EIxO_MODE where x is the controller letter (e.g., A, B, C, ...). The console 
environment variable is set with the command: 


SET EWx0_MODE media_selection 


The media_selection is defined by Table 9-18. 


Table 9-19 82559 Hardware Media Selection 
Media selection What is selected 
Twisted-pair 10BaseT (UTP) half-duplex 


Full duplex, twisted-pair 10BaseT (UTP) full-duplex 


Fast 100BaseTX (UTP) half-duplex 
FastFD (full duplex) 100BaseTX (UTP) full-duplex 
Autonegotiate Auto-negotiate speed and duplex (UTP) 


During driver initialization, a message is sent to the operator's console to indicate the console selection. 


If a console environment variable has been set with an unsupported media type for the actual device, then the 
driver selects a default media type. 


On 164 systems, there is no console environment variable equivalent, so the default setting is 
auto-negotiation. 


On Alpha and 164 systems, you can override the console environment variable setting or default setting of 
auto-negotiation by describing the media selection in the LANCP permanent device database. 
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9.5.3.10 DEGPA Gigabit Ethernet Devices 
The DEGPA series of Gigabit Ethernet NICs uses the Tigon2 chip, designed by Alteon Networks.. 
Table 9-20 lists and describes the devices and drivers of the DEGPA. 


Table 9-20 DEGPA Devices 
Device Characteristics 
DEGPA-SA 1000BaseSX (multimode fiber) 
DEGPA-TA 10BaseT (UTP), 100BaseTX (UTP), 1000BaseT (UTP) 


9.5.3.10.1  DEGPA Hardware Configuration The DEGPA NICs are supported only on Alpha systems. 
The DEGPA is not a bootable device and has no console support, therefore has no console environment 
variable mode setting for configuration, and the default setting is auto-negotiation. 


You can override the default setting of auto-negotiation by describing the media selection in the LANCP 
permanent device database. 


9.5.3.11 Broadcom 5700 Gigabit Ethernet Devices 


The Broadcom 5700 refers to a family of Gigabit Ethernet chips designed by Broadcom Corporation. The 
5700 NICs described here use two almost identical variants, the 5701 and 5708 chips. 


Table 9-21 Broadcom 5700 Characteristics 
Device Bus Characteritics 
DEGXA-SA PCI 1000BaseSX (multimode fiber) 
DEGXA-TA PCI 10BaseT (UTP), 100BaseTX (UTP), 1000BaseT (UTP) 
DEGXA-SB PCI-X 1000BaseSX (multimode fiber) 
DEGXA-TB PCI-X 10BaseT (UTP), 100BaseTX (UTP), 1000BaseT (UTP) 
BCM5703 (LOM) PCI 10BaseT (UTP), 100BaseTX (UTP), 1000BaseT (UTP) 
A6847A PCI 1000BaseSX (multimode fiber) 
A6825A PCI 10BaseT (UTP), 100BaseTX (UTP), 1000BaseT (UTP) 
AB352A PCI-X 10BaseT (UTP), 100BaseTX (UTP), 1000BaseT (UTP) 
A9782A PCI-X 1000BaseSX (multimode fiber) 
A9784A PCI-X 10BaseT (UTP), 100BaseTX (UTP), 1000BaseT (UTP) 
AB454A PCI-X 10BaseT (UTP), 100BaseTX (UTP), 1000BaseT (UTP) 
BCM5701 (LOM) PCI 10BaseT (UTP), 100BaseTX (UTP), 1000BaseT (UTP) 


9.5.3.11.1 5700 Hardware Configuration On Alpha systems, the 5700 driver uses the setting of a console 
environment variable to select the speed and duplex mode. The console environment variable is called 
EGx0_MODE where x is the controller letter (e.g., A, B, C, ...). The console environment variable is set with 
the command: 


SET EGxO_MODE media_selection 
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The media_selection is defined by Table 9-22. 


Table 9-22 5700 Hardware Media Selection 
Media selection What is selected 

auto Auto-negotiate speed and duplex (UTP) 

10mbps 10BaseT (UTP) half-duplex 

10mbps_full_duplex 10BaseT (UTP) full-duplex 

100mbps 100BaseTX (UTP) half-duplex 
100mbps_full_duplex 100BaseTX (UTP) full-duplex 

1000mbps 1000BaseT (UTP) half-duplex 


1000mbps_full_duplex 1000BaseT (UTP) full-duplex 


During driver initialization, a message is sent to the operator's console to indicate the console selection. 


If a console environment variable has been set with an unsupported media type for the actual device, then the 
driver selects a default media type. 


An Alpha system console may assign a controller letter to an adapter differently from OpenVMS, since 
OpenVMS EW devices include Tulip, DEGPA, Broadcom 5700, but the console only recognizes 5700 devices as 
EW devices. In this case you can compare the MAC address listed for the device at the console SHOW 
CONFIGURATION and LANCP SHOW CONFIGURATION commands. 


On 164 systems, there is no console environment variable equivalent, so the default setting is 
auto-negotiation. 


On Alpha and 164 systems, you can override the console environment variable setting or default setting of 
auto-negotiation by describing the media selection in the LANCP permanent device database. 


9.5.3.12 Intel 82540 Gigabit Ethernet Devices 


The Intel 82540 refers to a family of Gigabit Ethernet chips designed by Intel Corporation. The variant used 
on these NICs is the Anvik2 chip. 


Table 9-23 Intel 82540 Characteristics 
Device Bus Characteritics 
A7011A PCI-X Dual 1000BaseSX (multimode fiber) 
A7012A PCI-X Dual 10BaseT (UTP), 100BaseTX (UTP), 1000BaseT (UTP) 


9.5.3.12.1 82540 Hardware Configuration The 82540 devices are supported only on 164 systems. The 
default setting is autonegotiation. 


You can override the default setting of auto-negotation by describing the media selection in the LANCP 
permanent device database. 


9.5.3.13 Shared Memory Ethernet Device 


The Shared Memory device is an emulated Ethernet device that uses Galaxy Shared Memory on Alpha 
systems. Each Galaxy partion is considered a network node. The driver uses shared memory to send packet 
data from one node to another. Applications see the Shared Memory device as just another Ethernet device. 
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9.5.4 FDDI LAN Devices 
FDDI devices support the following media 


e Multimode optical fiber, using two strands of fiber to provide full-duplex communication. 

e Category 5 unshielded twisted-pair cabling (UTP), using two of the four pairs of wires to provide full 
duplex communication. 

9.5.4.1 DEMFA FDDI Device 


The DEMFA is an XMI bus FDDI device that is supported on VAX and Alpha systems that have an XMI bus. 
The DEMFA is a firmware based FDDI controller that uses an Motorolla 68000 microprocessor to implement 
a host interface and the necessary FDDI support functionality. 


Table 9-24 DEFMA FDDI Charactertics 


Device Bus Characteristics 


DEMFA XMI Multimode fiber, 100 megabits/second 


9.5.4.2 DEFZA FDDI Device 
The DEFZA is a TurboChannel FDDI device supported on VAX and Alpha TURBOchannel-based systems. 


Table 9-25 DEFZA FDDI Charactertics 
Device Bus Characteristics 
DEFZA TurboChannel Multimode fiber, 100 megabits/second 
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Table 9-26 PDQ FDDI Charactertics 
Device Bus Characteristic 

DEFQA-SA QBUS Multimode fiber, single attached station (SAS), 100 megabits/second 
DEFQA-DA QBUS Multimode fiber, dual attached station (DAS), 100 megabits/second 
DEFQA-SF QBUS UTP, single attached station (SAS), 100 megabits/second 
DEFQA-DF QBUS UTP, dual attached station (DAS), 100 megabits/second 
DEFTA-AA TurboChannel Multimode fiber, single attached station (SAS), 100 megabits/second 
DEFTA-DA TurboChannel Multimode fiber, dual attached station (DAS), 100 megabits/second 
DEFTA-UA TurboChannel UTP, single attached station (SAS), 100 megabits/second 
DEFTA-MA TurboChannel UTP, dual attached station (DAS), 100 megabits/second 
DEFAA-AA FutureBus+ Multimode fiber, single attached station (SAS), 100 megabits/second 
DEFAA-DA FutureBus+ Multimode fiber, dual attached station (DAS), 100 megabits/second 
DEFEA-AA EISA Multimode fiber, single attached station (SAS), 100 megabits/second 
DEFEA-DA EISA Multimode fiber, dual attached station (DAS), 100 megabits/second 
DEFEA-UA EISA UTP, single attached station (SAS), 100 megabits/second 
DEFEA-MA EISA UTP, dual attached station (DAS), 100 megabits/second 
DEFPA-AA PCI Multimode fiber, single attached station (SAS), 100 megabits/second 
DEFPA-DA PCI Multimode fiber, dual attached station (DAS), 100 megabits/second 
DEFPA-UA PCI UTP, single attached station (SAS), 100 megabits/second 
DEFPA-MA PCI UTP, dual attached station (DAS), 100 megabits/second 


9.5.5 Token Ring LAN Devices 


Token Ring devices support the following media types: 


STP — Shielded twisted-pair cabling, type 1 STP, using 2 pairs of wires in crossover form. The cables 
have DB-9 connectors on them. 


UTP — Unshielded twisted-pair cabling, type 3 UTP, using 2 pairs of wires in crossover form to provide 
full-duplex communications. 
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9.5.5.1 TMS380 Token Ring Devices 


The Texas Instruments TMS380 chip forms the basis of a family of Token Ring devices. These are shown in 
Table 9-27. 


Table 9-27 TMS380 Token Ring Charactertics 


Device Bus Characteristics 


DETRA TurboChannel 4/16 megabits/second, STP or UTP 


DW300 EISA 4/16 megabits/second, STP or UTP 

DW110 ISA 4/16 megabits/second, STP or UTP, aka P1392+ 

TC4048 PCI 4/16 megabits/second, STP or UTP, made by Thomas Conrad Corporation 
M8154 PCI 4/16 megabits/second, STP or UTP, made by Racore Computer Products, Inc. 


9.5.5.1.1 ISA TMS380 Hardware Configuration The DW110 is a bus mastering DMA device on the ISA 
bus. In addition to setting up the ISA I/O parameters, you may configure ring speed (4 or 16 megabits/second) 
and media (UTP or STP). By using LANCP you can also configure ring speed and media during system 
startup. Example 9-1 shows how to configure the OpenVMS software to use the DW110 device. 


The method for configuring an ISA TMS380 device is to type ‘isacfg' at the console prompt (>>>). For complete 
information on using 'isacfg' from your console prompt, refer to the hardware documentation associated with 
your system for more information. 


The following example illustrates a configuration of: 


e Slot 4 

e IRQ 10 

e DMA channel 7 

e 6Base %x4e20 

e Shielded twisted pair (STP) 
e Ring speed of 16 


Example 9-1 Using the 'isacfg' at Console Prompt with the DW110 


>>> isacfg -slot 4 -etyp 1 -ena 1 -irg0 %xa -dmachan0O 7 
-iobaseO %x4e20 -handle "DW11,STP,16" -mk 


The -mk command makes an isacfg entry for an ISA device at slot 4. It is a Single port type of device (-etyp 1). 
The -handle parameter tells the operating system that this is a DW110 device, that STP media is to be used, 
and the ring speed is 16. 


9.5.6 ATM LAN Devices 


Asynchronous transfer mode (ATM) is a cell-oriented switching technology that uses fixed-length packets to 
carry different types of data. 


The ATM communicates by first establishing endpoints between two computers with a virtual circuit (VC) 
through one or more ATM switches. ATM then provides a physical path for data flow between the endpoints 
by either a permanent virtual circuit (PVC), or a switched virtual circuit (SVC). 
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OpenVMS provides LAN Emulation Client (LEC) support over ATM. The LAN Emulation Client software 
supports IEEE/802.3 Emulated LANs, and UNI 3.0 or UNI 3.1 and the following maximum frame size (in 
bytes): 1516, 4544, and 9234. 


The Emulated LAN driver provides the means for communicating over the LAN ATM. The device type for the 
Emulated LAN device is DT$_EL_ELAN. 


The device name for the Emulated LAN is: 
ELcu 
where c is the controller and u is the unit number (for example, ELAO). 


ATM devices support the following media types: 


e Multimode optical fiber, using two strands of fiber to provide full-duplex communication. 


e Category 5 unshielded twisted-pair cabling (UTP), using two of the four pairs of wires to provide 
full-duplex communication. 


9.5.6.1 OTTO ATM Devices 


OTTO refers to a family of ATM adapters developed by Digital Equipment Corporation. The TurboChannel 
adapter is named OTTO. The PCI DGLPB adapter is named OPPO. OTTO and OPPO are programmable 
logic designs where the driver loads firmware onto the adapters to program the FPGA devices. The DGLPA is 
a single chip ATM adapter that is a considerably different implementation but lumped into this same 
category. 


Table 9-28 OTTO ATM Charactertics 
Device Bus Characteristics 
DGLTA TurboChannel 155 megabits/second (OC3), multimode fiber 
DGLPB PCI 155 megabits/second (OC3), multimode fiber 
DGLPA-UA PCI 155 megabits/second (OC3), UTP 
DGLPA-FA PCI 155 megabits/second (OC3), multimode fiber 


The OTTO drivers support ATM LAN Emulation according to the ATM LANE standards, and Classical IP 
over ATM according to RFC 1577. 
9.5.6.2 FORE ATM Devices 


The DAPBA and DAPCA are ATM adapters made by Fore Networks, Inc., now part of Marconi Corporation, 
Ple. 


The FORE drivers support ATM LAN Emulation according to the ATM LANE standards. 


Table 9-29 FORE ATM Charactertics 
Device Characteristics 
DAPBA-UA 155 megabits/second (OC3), UTP 
DAPBA-FA 155 megabits/second (OC3), multimode fiber 
DAPCA-FA 622 megabits/second (OC12), multimode fiber 
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For each DAPBA, HP recommends increasing the SYSGEN parameter NPAGEVIR by 3000000. For each 
DAPCA, HP also recommends increasing NPAGEVIR by 6000000. To do this, add the ADD_NPAGEVIR 

parameter to MODPARAMS.DAT and then run AUTOGEN. For example, add the following command to 

MODPARAMS.DAT on a system with two DAPBAs and one DAPCA: 


ADD_NPAGEVIR = 12000000 


The following restrictions apply to the DAPBA and DAPCA adapters. 


e The adapter cannot be located on a PCI bus that is located behind a PCI-to-PCI bridge. Systems that have 
this configuration are the following: 


— HP Personal AlphaWorkstation 600 (MIATA GL) 
— AlphaStation 1000A (Noritake) 

— HP Professional Workstation XP1000 (MONET) 
— AlphaServer 2000 and 2100 (SABLE) 


e Classical IP is not supported. 


9.5.6.3 Permanent Virtual Circuits (PVC) 


Permanent Virtual Circuits are set up and torn down by prior arrangement. They are established manually 
by a user before the sending of any data between endpoints on a network. Some PVCs are defined directly on 
the switch; others are predefined for use in managing switched virtual circuits (SVCs). 


9.5.6.4 Switched Virtual Circuits (SVC) 


Switched virtual circuits require no operator interaction to create and manage connections between 
endpoints. Software sets up and tears down connections dynamically as they are needed through the request 
of an endpoint. 


9.5.6.5 LAN Emulation over an ATM Network 


LAN emulation over an ATM network network allows existing applications to run essentially unchanged 
while also allowing the applications to run on computers directly connected to the ATM network. The LAN 
emulation hides the underlying ATM network at the media access control (MAC) layer, which provides device 
driver interfaces. 
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Table 9-30 shows the four components that make up a LAN emulation over ATM network. Of the four 
components, OpenVMS supports only the LAN emulation client (LEC). The remaining components are 
provided by the ATM switch. 


Table 9-30 Components of LAN Emulation over an ATM Network 
Component Function 
LAN emulation client (LEC) Provides a software driver that runs on a network client and enables 


LAN clients to connect to an ATM network. 


LAN emulation server (LES) Maintains a mapping between LAN and ATM addresses by resolving 
LAN media access control (MAC) addresses with ATM addresses. 


Broadcast and Unknown Server Maintains connections with every LAN emulation client (LEC) in the 

(BUS) network. For broadcast messages, the BUS sends messages to every 
attached LEC. The LECs then forward the message to their 
respectively attached LANs. For multicast messages, the BUS sends 
messages to only those LECs that have devices in the multicast group. 
For a LEC that wants to send a regular message whose destination 
MAC address is unknown, the BUS can be used to determine this 


address. 
LAN emulation configuration Provides a service for LAN emulation clients by helping to determine 
server (LECS) which emulated LAN each of the LEC's registered users should join, 


since each client can specify which emulated LAN to join. 


The LEC exists on all ATM-attached computers that participate in the LAN emulation configuration. LEC 
provides the ATM MAC-layer connectionless function that is transparent to the LAN-type applications. The 
LEC, LES, and BUS can exist on one ATM-attached computer or on separate computers. The server functions 
usually reside inside an ATM switch, but can be implemented on client systems. 
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9.5.6.6 LAN Emulation Topology 
Figure 9-10 shows the topology of a typical emulated LAN over ATM. 


Figure 9-10 Emulated LAN Topology 
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9.5.6.7 Classical IP Over an ATM Network 


Classical IP (CLIP) implements a data-link level device that has the same semantics as an Ethernet interface 
(802.3). This interface is used by a TCP/IP protocol to transmit 802.3 (IEEE Ethernet) frames over an ATM 
network. The model that OpenVMS follows for exchanging IP datagrams over ATM is based on RFC 1577 
(Classical IP over ATM). 


For information on using LANCP commands to manage Classical IP, refer to the HP OpenVMS System 
Management Utilities Reference Manual. 
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9.5.6.8 Specifying the User to Network Interface (UNI 


The ATM software is set to autosense the UNI version by default. Setting bit 3 of the system parameter, 
LAN_FLAGS, to 1 enables UNI 3.0 over all ATM adapters. Setting bit 4 of the system parameter, 
LAN_FLAGS, to 1 enables UNI 3.1 over all ATM adapters. 


9.5.6.9 Enabling SONET/SDH 


The ATM drivers have the capability of operating with either synchronous optical network (SONET) or 
Synchronous Digital Hierarchy (SDH) framing. Setting bit 0 of the system parameter, LAN_FLAGS, to 1 
enables SDH framing. Setting bit 0 of the system parameter, LAN_FLAGS, to 0 enables SONET framing 
(default). For this to take affect, the system parameter must be specified correctly before the ATM adapter 
driver is loaded. 


9.5.6.10 Booting 
OpenVMS Alpha does not support ATM adapters as boot devices. 


9.5.6.11 Configuring an Emulated LAN (ELAN) 


The LANCP utility sets up an Emulated LAN (ELAN). If the ELAN is defined in the permanent database, 
these settings take effect at boot time. To define the commands in the permanent database for specific 
adapters, you invoke the DEFINE DEVICE commands. Once these commands define the adapters in the 
permanent database, the ELAN can be started during system startup. 


You can also invoke the LANCP SET commands to start up an ELAN after the system is booted. 


The following example shows the DEFINE DEVICE commands that define the adapter in the permanent 
database: 


S$ mcr lancp 

LANCP> define device ela0/elan=create 

LANCP> define device ela0/elan=(parent=hwa0,type=csmacd, size=1516) 
LANCP> define device ela0/elan=(descr="An ATM ELAN") 

LANCP> define device ela0/elan=enable=startup 

LANCP> list dev ela0/param 


Device Characteristics, Permanent Database, for ELAO: 
Value Characteristic 


HWAO Parent ATM device 
"An ATM ELAN" Emulated LAN description 
1516 Emulated LAN packet size 
CSMA/CD Emulated LAN type 
Yes Emulated LAN enabled for startup 


LANCP> exit 
$ 


The following example shows the SET DEVICE commands required for setting up an ELAN with the desired 
parameters. Note that some of the commands generate a console message. 


S$ mcr lancp 
LANCP> set dev ela0/elan=create 


$SSSSSSSS%S% OPCOM 26-MAR-2001 16:57:12.89 %%%%%%%3%%%% 
Message from user SYSTEM on ALPHA1 
LANACP LAN Services 
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Found LAN device ELAO, 


hardware address 00-00-00-00-00-00 


LANCP> set dev 
LANCP> set dev 


ela0/elan=(parent=hwa0,type=csmacd, size=1516) 
ela0/elan=(descr="An ATM ELAN") 


LANCP> set dev 


ELDRIVER, LAN 
ELDRIVER, LAN 


aro 


LANCP> sho dev 


Device Characteristics 


ela0/elan=enable=startup 


ela/char 


Value 
Normal 
External 
CSMA/CD 
16 

32 

No 

No 


Unspecified 


"An ATM ELAN" 
3999990000000008002B 


10 
CSMA/CD 
"HWAO" 


A57E80AA000302FF1300 


LANCP> exit 
$ 


Enabled 


Emulation event at 26-MAR-1996 16:57:28.78 
Emulation startup: Emulated LAN 1 on device ELAO 


ELAO: 
Characteristic 


Controller mode 

Internal loopback mode 
Communication medium 
Minimum receive buffers 
Maximum receive buffers 
Full duplex enable 

Full duplex operational 
Line media 

Line speed (megabits/second) 
Communication medium 

Parent ATM Device 

Emulated LAN Description 
LAN Emulation Server ATM Address 


Emulated LAN State 


For information about using LANCP and system manager commands with qualifiers for LAN emulation over 
ATM networks, refer to the HP OpenVMS System Management Utilities Reference Manual and HP OpenVMS 
System Manager’s Manual. 


9.6 LAN Device Information 


You can obtain information on controller characteristics by using the Get Device/Volume Information 
($GETDVD system service. (Refer to the HP OpenVMS System Services Reference Manual.) 
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$GETDVI returns controller characteristics when you specify the item code DVI$_DEVCHAR. Table 9-31 
lists these characteristics, which are defined by the $DEVDEF macro and in the file 
SYS$LIBRARY:DEVDEF.H. 


Table 9-31 Ethernet Controller Device Characteristics 


Characteristic Meaning 


Static Bits (Always Set) 


DEV$M_AVL Device is available. 
DEV$M_IDV Input device. 
DEV$M_NET Network device. 
DEV$M_ODV Output device. 


DVI$_DEVTYPE and DVI$_DEVCLASS return the device type and device class names, which are defined by 
the $DCDEF macro and in the file SYS$LIBRARY:DCDEF.H. The device class name for the LAN Ethernet 
controllers listed in Section 9.2.1 and Section 9.2.2 is always DC$_SCOM. 


DVI$_DEVBUFSIZ returns the maximum message size. The maximum send or receive message size depends 
on the packet format and whether padding (NMA$C_PCLI_PAD) is enabled (see Sections Section 9.7.1 and 
Section 9.7.2 ). DVI$_DEVDEPEND returns the unit and line status bits and the error summary bits in a 
longword field as shown in Figure 9-11. 


Figure 9-11 DVI$_DEVDEPEND Returns 
31 24 23 16 15 87 0 


Not Used Unit and Line Not Used 


Status 


ZK5932GE 


Table 9-32 lists the status values and their meanings. These values are defined by the $XMDEF macro. 
XM$M_STS_ACTIVE is set when the port is started. XM$M_STS_BUFFAIL and XM$M_STS_TIMO are 
dynamically set and cleared by the LAN driver. 


Table 9-32 Ethernet Controller Unit and Line Status 
Status Meaning 
XM$M_STS_ACTIVE Port is active. 
XM$M_STS_BUFFAIL Attempt to allocate a system receive buffer failed. 
XM$M_STS_TIMO Timeout occurred. 
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The error summary bits are set when an error occurs. They are read-only bits. If an error is fatal, the 
Ethernet port is shut down. Table 9-33 lists the error summary bit values and their meanings. 


Table 9-33 Error Summary Bits 
Error Summary Bit Meaning 
XM$M_ERR_FATAL Hardware or software error occurred on the controller. 
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9.7 LAN Function Codes 


The LAN drivers can perform logical, virtual, and physical I/O operations. The basic functions are read, write, 
set mode, set characteristics, sense mode, and sense characteristics. Table 9-34 lists these functions and their 
codes. The following sections describe these functions in greater detail. 


Table 9-34 LAN I/O Functions 
Function Code Arguments Type! Function Modifiers Function 

10$_READLBLK2 P1,P2,[P5] L 10$M_NOW Read logical block. 

10$_ READVBLK? P1,P2,[P5] Vv 10$M_NOW Read virtual block. 

10$_ READPBLK2 P1,P2,[P5] P I0$M_NOW Read physical block. 

10$ WRITELBLK?  P1,P2,[P4],P5 — L I0$M_RESPONSE Write logical block. 

10$ WRITEVBLK?  P1,P2,[P4],P5  V IO$M_RESPONSE Write virtual block. 

10$_WRITEPBLK‘ _P1,P2,[P4],P5 =P I0$M_RESPONSE Write physical block. 

10$_SETMODE P1,[P2],P3? L IO$M_CTRL Set controller 
IO$M_STARTUP characteristics and 
I0$M_SHUTDOWN controller state for 
IO$M_ATTNAST subsequent operations. 
IO$M_SET_MAC 
IO$M_UPDATE_MAP 
IO$M_ROUTE 

10$_SETCHAR P1,[P2],P32 P IO$M_CTRL Set controller 
IO$M_STARTUP characteristics and 
I0$M_SHUTDOWN controller state for 
IO$M_ATTNAST subsequent operations. 
IO$M_SET_MAC 
IO$M_UPDATE_MAP 
IO$M_ROUTE 

10$_SENSEMODE [P1],[P2] L IO$M_CTRL Sense controller 
I0$M_SENSE_MAC characteristics and return 
I0$M_SHOW_MAP them in specified buffers. 
IO$M_SHOW_ROUTE 

10$_SENSECHAR [P1],[P2] P IO$M_CTRL Sense controller 
IO0$M_SENSE_MAC characteristics and return 
I0$M_SHOW_MAP them in specified buffers. 
I0$M_SHOW_ROUTE 


1. V= virtual, L=logical, P=physical ( There is no functional difference in these operations.) 
2. On OpenVMS Alpha and 164, P1 and P5 support 64-bit addresses. 

3. On OpenVMS Alpha, P1, P4, and P5 support 64-bit address. 

4. The P1 and P3 arguments are only for attention AST QIOs. 
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Note that the LAN device drivers do not differentiate among logical, virtual, and physical I/O functions; all 
are treated identically. 


9.7.1 Read 


Read functions directly transfer data from a packet received from another port on the Ethernet into the 
virtual memory address space of the user process. The operating system provides the following function codes: 


¢ J10$_READLBLK—Read logical block 
e I0$ READVBLK—Read virtual block 
¢ J0$_READPBLK—Read physical block 


Received messages are buffered in system memory and then copied to the user's buffer when a read operation 
is performed. 


The read functions take the following device- or function-dependent arguments: 


e P1—tThe starting virtual address of the buffer that is to receive data. On OpenVMS Alpha and [64 
systems, P1 can be a 64-bit address. 


e P2—The size of the receive buffer in bytes. 


e P5—The address of a buffer where the LAN driver returns packet header information. This is an optional 
argument. The information returned depends on the packet format enabled with the set mode QIO. The 
size of the buffer must be 14 bytes for an Ethernet format packet, 16 bytes for an IEEE 802 format packet, 
and 20 bytes for an 802 extended format packet. Note that the information returned is not the entire 
packet header but the header information less any length or size fields. The IOSB, if specified, is where 
the packet length information is returned. For FDDI, if received access control (RAC) is on, then 1 byte 
must be added to these sizes. 


For Token Ring, this buffer must be at least 54 bytes in length due to a possible variable length source 
routing header. 
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If NMA$C_PCLI_PRM (see Table 9-39) is enabled, the P5 buffer must be at least 20 bytes for Ethernet 
and 21 bytes for FDDI. Figure 9-12 shows the format of the three buffers. On OpenVMS Alpha and 164 
systems, P5 can be a 64-bit address. 


Figure 9-12 Read Function P5 Buffer 


Ethernet Format: 


6 Byte Destination 
Address 


6 Byte Source Address 


2 Byte Protocol Type 


IEEE 802 Format: 


6 Byte Destination 
Address 


6 Byte Source Address 


SSAP DSAP 
1 or 2 Byte CTL Field 


802 Extended Format: 


6 Byte Destination 
Address 


6 Byte Source Address 


SSAP DSAP 
1 Byte CTL Field 


5 Byte Protocol Identifier 


ZK-1126-Al 
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The P1 and P2 arguments must always be specified; the P5 argument is optional. However, if P5 is not 
specified, you will be unable to determine the source of the received message. 


If the size of the user data in a receive message is larger than the value of the NMA$C_PCLI_BUS parameter, 
the message is not given to the user, even if there is sufficient space in the user's receive buffer. 


If the size of the user data in a receive message is larger than the size specified in P2 (and less than or equal 
to the value of the NMA$C_PCLI_BUS parameter), the P1 buffer is filled and SS$_DATAOVERUN is 
returned in the I/O status block. 


Table 9-35 lists the maximum user data sizes that can be received for Ethernet, FDDI, and Token Ring 
protocols. 


Table 9-35 Maximum User Data Sizes for Ethernet, FDDI, and Token Ring 
Packet Format Ethernet FDDI Token Ring 
Ethernet format without padding 1500 4470 4418 
Ethernet format with padding 1498 4468 4416 
802 format with 1-byte CTL field 1497 4475 4423 
802 format with 2-byte CTL field 1496 4474 4422 
802E format 1492 4470 4418 


Table 9-36 lists the maximum user data sizes that can be received for LAN emulation over ATM protocol. 


Table 9-36 Maximum User Data Sizes for LAN Emulation over ATM 
Packet Format ATM ELAN size: 1516 4544 9234 
Ethernet format without padding 1500 4528 9218 
Ethernet format with padding 1498 4526 9216 
802 format with 1-byte CTL field 1497 4525 9215 
802 format with 2-byte CTL field 1496 4524 9214 
802E format 1492 4520 9210 


For 802 format packets, the P5 buffer always contains the DSAP and SSAP in the bytes at offset 12 and 13. 
The next one or two bytes (offsets 14 and 15) following the SSAP contain the control field value. For Class I 
service, the control field value is always 1 byte in length and will always be placed in the byte at offset 14 of 
this buffer. For user-supplied service, you have to determine the length of the control field value according to 
the IEEE 802.2 Standard. 


For Token Ring, if received access control (RAC) is on, the first byte of the P5 buffer contains the frame control 
(FC) field. 


For FDDI, if RAC is on, the first byte of the P5 buffer contains the FC field. 


The read functions can take the following function modifier: 


¢ IO$M_NOW—Complete the read operation immediately with a received message (if no message is 
currently available, return a status of SS$_ENDOFFILE in the I/O status block). 
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9.7.2 Write 


Write functions provide for the direct transfer of data from the virtual memory address space of the user 
process to the communications medium. The operating system provides the following function codes: 


e 10$_WRITELBLK—Write logical block 
e IO$ WRITEVBLK—Write virtual block 
¢ I0$_WRITEPBLK—Write physical block 


Transmitted messages are copied from the buffer of the requesting process to a system buffer for 
transmission. 


The write function takes the following device- or function-dependent arguments: 


e P1—tThe starting virtual address of the buffer containing the data to be transmitted. On OpenVMS Alpha 
and I64 systems, P1 can be a 64-bit address. 


e P2—The size of the buffer in bytes. 


e P4—The address of a quadword that points to a buffer that contains the DSAP and CTL field values 
(optional). (See Section 9.4.6.6.4.) The first longword is the buffer length; the second longword is the 
address of the buffer. This argument is used only for ports with the 802 packet format. The format of the 
buffer is: 


23 8 7 0 


CTL DSAP 


ZK4801GE 


On OpenVMS Alpha and 164 systems, P4 can be a 64-bit address. 


e P5—The address of a 6-byte buffer that contains the destination address. For FDDI, if XFC is specified as 
zero on startup, the first byte of the P5 buffer contains the low-order 3 bits of the FC field to be 
transmitted. On OpenVMS Alpha and I64 systems, P5 can be a 64-bit address. 


If the device is in promiscuous mode (NMA$C_PCLI_PRM; see Table 9-39), you must pass a larger buffer 
with additional information positioned after the destination address. For Ethernet packet format, the 
buffer must be 8 bytes with the 2-byte protocol type following the destination address. For 802 packet 
format, the buffer must be 7 bytes with the 1-byte source SAP following the destination address. For 802 
extended packet format, the buffer must be 11 bytes with the 5-byte protocol identifier following the 
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destination address. The Source SAP cannot be a group SAP or the SNAP SAP. Figure 9-13 shows the 
format of the P5 buffer. For FDDI with XFC specified as zero on startup, 1 byte must be added to these 
sizes for the FC field. 


Figure 9-13 Write Function P5 Buffer 


6Byte Destination 


Address 4 


2Byte Protocol Type, 1Byte Source SAP, 


a or 5Byte Protocol Identifier * T 


“Only if the channel is in promiscuous mode. 
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Table 9-37 lists the maximum user data sizes that can be specified by P2 and received for Ethernet, FDDI, 
and Token Ring protocols. 


Table 9-37 Maximum Message Sizes for Ethernet, FDDI, and Token Ring 
Packet Format Ethernet FDDI Token Ring 
Ethernet format without padding 1500 4470 4418 
Ethernet format with padding 1498 4468 4416 
802 format with 1-byte CTL field 1497 4475 4423 
802 format with 2-byte CTL field 1496 4474 4422 
802E format 1492 4470 4418 


Table 9-38 lists the maximum user data sizes that can be specified by P2 and received for LAN emulation over 
ATM protocol. 


Table 9-38 Maximum Message Sizes for LAN Emulation over ATM 
Packet Format ATM ELAN size: 1516 4544 9234 
Ethernet format without padding 1500 4528 9218 
Ethernet format with padding 1498 4526 9216 
802 format with 1-byte CTL field 1497 4525 9215 
802 format with 2-byte CTL field 1496 4524 9214 
802E format 1492 4520 9210 


If P2 specifies a message size larger than that allowed, the driver returns the status SS$_IVBUFLEN in the 
I/O status block. 
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If the P4 buffer is specified, it must be at least 3 bytes long. The first byte is always the DSAP; the next two 
bytes are used to determine the CTL field value. The DSAP value cannot be the SNAP SAP. 


The CTL field value is either a 1-byte or 2-byte value. If the two least significant bits of the low-order byte of 
the CTL field contain the bit values 11, just the low-order byte of the CTL field is used as the CTL field value. 
Otherwise, both bytes of the CTL field are used as the CTL field value. 


If the driver uses only the low-order byte of the CTL field, you still must pass at least a 3-byte buffer. In this 
case, the driver uses the low-order byte of the CTL field and ignores the high-order byte. 


If Class I service is enabled, only 1-byte CTL field values can be passed. If user-supplied service is enabled, 
then both 1- and 2-byte CTL field values are valid. If Class I service is enabled, the CTL field value must be 
one of the three command values: UI, XID, or TEST. 


Regarding 802 ports, you can receive packets for the SAP enabled with the IO$_SETMODE or 
I0$_SETCHAR QIOs and can transmit packets destined for a different SAP. This is similar to an Ethernet 
port receiving packets for one protocol type and transmitting packets with a different protocol type (which is 
not possible with the current Ethernet $QIO interface). It is expected that most 802 format applications will 
want to process only receive packets from a source SAP that matches the SAP enabled on their port. To do 
this, the read function (see Section 9.7.1) has been enhanced to return the source SAP to you. To verify that 
the source SAP of an incoming packet matches the SAP enabled on the port, you need only match the source 
SAP returned by the read function with the SAP enabled on the port. 


The write function can take the following function modifier: 


¢ IO$M_RESPONSE—Transmit a response packet (sets the low-order bit in the SSAP field). This allows 
users with user-supplied service enabled to respond to certain 802 format command packets. 
IO$M_RESPONSE can be specified only when you have the 802 packet format enabled. The 802 packet 
format ports, with Class I service enabled, result in an error if you attempt to transmit a response 
message with a CTL field value of unnumbered information (UI). 


9.7.3. Set Mode and Set Characteristics 

The operating system provides the following two function codes: 
¢ I10$_SETMODE 

e I10$_SETCHAR 


Other than the privilege check, these two function codes are treated the same by the LAN drivers. This 
section refers to the IO$_SETMODE function code only, even though applications can use either function 
code. 


The set mode function code is used to perform many different functions. These different functions are 
distinguished by the modifiers set with the function code. The LAN drivers support the following set mode 
requests: 


e I0$_SETMODE!IO$M_CTRL — Set or modify port attributes 

¢ J10$_SETMODE!IO$M_CTRL!IO$M_STARTUP — Set port attributes and start port 

¢ I0$_SETMODE!IO$M_SET_MAC — Set medium attributes 

¢ I0$_SETMODE!IO$M_CTRL!IO$¢M_SHUTDOWN — Shut down port 

e 10¢$ SETMODE!IO$M ATTNAST — Enable attention AST 

¢ IO$M_SETMODE!IO$M_UPDATE_MAP — Update functional address mapping table (Token Ring only) 
¢ IO$M_SETMODE!IO$M_ROUTE — Update source routing cache table (Token Ring only) 


375 


Local Area Network (LAN) Device Drivers 
LAN Function Codes 


The following sections describe these functions in detail. 


9.7.3.1 Set Controller Mode 


Once a port is created using the $ASSIGN system service, you can set the port attributes and start the port 
using the requests listed in the previous section. Note that in most cases only 
10$_SETMODE!IO$M_CTRL!IO$M_STARTUP is issued because it sets the port attributes and starts the 
port with one request. IO$ SETMODE!IO$M_CTRL is most often used to modify port attributes after the 
port has been started. 


If the function modifier IO$M_STARTUP is specified, the LAN port is started. If IO$M_STARTUP is not 
specified, the specified characteristics are modified. 


This function takes the following device- or function-dependent argument: 


e P2—The address of a quadword descriptor for an extended characteristics buffer. The first longword of the 
descriptor is the buffer length; the second longword is the address of the buffer. The P2 argument is 
optional. 


The P2 buffer consists of a series of 6-byte or counted string entries. The first word of each entry contains the 
parameter identifier (ID) of an attribute, followed by either a longword that contains one of the (binary) 
values that can be associated with the parameter ID or a counted string. Counted strings consist of a word 
that contains the size of the character string followed by the character string. Figure 9-14 shows the format 
for this buffer. 


Figure 9-14 P2 Extended Characteristics Buffer 


etc. 


ZK1177GE 


Table 9-39 is an alphabetic listing of the parameter IDs and values that can be specified in the P2 buffer. 
These parameter IDs are applicable to all LAN controllers, except where otherwise noted. The $NMADEF 
macro defines these values. The $NMADEF macro is included in the macro library SYS$LIBRARY:LIB.MLB. 
(Table 9-39 lists the parameters that can be used with each of the packet formats, and indicates which are 
required, which are optional, and which generate the SS$_BADPARAM error.) 
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If the status SS$_BADPARAM is returned in the first word of the I/O status block, the second longword 
contains the parameter ID of the parameter in error. 


Table 9-39 P2 Attributes 


Parameter ID 


Meaning 


NMA$C_PCLI_ACC 


NMA$C_PCLI_BFN 


NMA$C_PCLI_BUS 


Protocol access mode. This optional parameter determines the access mode 
for the protocol type. NMA$C_PCLI_ACC is valid only for ports using 
Ethernet packet format. 


NMA$C_PCLI_ACC is valid for ports using 802E packet format. 
One of the following values can be specified: 

e NMA$C_ACC_EXC — Exclusive mode (default) 

e NMA$C_ACC_SHR — Shared-default user mode 

e NMA$C_ACC_LIM — Shared-with-destination mode 


Section 9.4.8 provides a description of protocol type sharing. 


Section 9.4.8 provides a description of protocol type PID sharing. 
NMA$C_PCLI_ACC is passed as a longword value. 


Number of receive buffers to preallocate (default = 1). NUA$C_PCLI_BFN 
can have a maximum value of 255. This optional parameter is specified on a 
per-port basis. 


NMA$C_PCLI_BFN is passed as a longword value. 


NMA$C_PCLI_BFN represents the number of receive messages the LAN 
driver will hold for a port when the port has no read QIOs posted to the 
driver. 


Any message received for this port that is larger than this parameter value 
is discarded. 


Maximum allowable port receive data size, that is, message length (default 
= 512 bytes). NMA$C_PCLI_BUS can have a maximum value of 9234. 


This optional parameter is specified on a per-port basis. It is passed as a 
longword value. 
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Table 9-39 P2 Attributes (Continued) 


Parameter ID 


Meaning 


NMA$C_PCLI_CCA 


Can change address. This optional parameter enables applications to start 
before DECnet starts. DECnet may attempt to set the physical address of 
the controller when it starts. Ethernet devices support only one physical 
address, and so all applications that are using the same device must also use 
the same physical address. If applications that do not use the DECnet 
address start before DECnet, DECnet is not able to start on that controller 
unless the other applications that have already started have all specified 
NMA$C_PCLI_CCA to be ON. 


This parameter is not applicable to FDDI because FDDI devices can run 
with more than one physical address; however, no error is returned if this 
parameter is supplied for FDDI devices. 


The application receives no indication whatsoever that the physical address 
has changed. 


This parameter is passed as a longword. One of the following values can be 
specified: 


¢ NMA$C_STATE_ON — The physical address can be changed. 


¢ NMA$C_STATE_OFF — The physical address cannot be changed 
(default). 
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Table 9-39 P2 Attributes (Continued) 


Parameter ID 


Meaning 


NMA$C_PCLI_CON! 


Controller mode. This optional parameter determines whether transmit 
packets are to be looped back at the controller. One of the following values 
can be specified: 


NMA$C_LINCN_NOR — Normal mode (default) 
NMA$C_LINCN_LOO — Loopback mode 


The only messages looped back are those acceptable to the controller as 
receive messages, that is, those messages that possess at least one of the 
following characteristics: 


e Matching physical address (see Section 9.4.5) 
e Matching multicast address (see Section 9.4.5) 
e Promiscuous mode (NMA$C_PCLI PRM) is in the ON state 


e Destination address is a multicast address and all multicasts are 
enabled (NMA$C_PCLI MLT is in the ON state) 


NMA$C_PCLI_CON affects all ports on a single controller. It is passed as a 
longword value. 


For the DELUA, DEBNA, DEBNI, DEQTA, PMAD, DEMNA, and DESVA, 
the following list shows the maximum amount of user data that can be 
looped: 


Ethernet format without padding — 18 bytes 
Ethernet format with padding — 16 bytes 
802 format with 1-byte CTL field — 15 bytes 
802 format with 2-byte CTL field — 14 bytes 
802 extended format—10 bytes 


When the DEUNA is in loopback mode, the driver always enables echo mode 
(NMA$C_PCLI_EKO is in the ON state). 


Not all devices support loopback mode. If normal mode is not specified, the 
request is completed with SS$_BADPARAM status. 
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Table 9-39 P2 Attributes (Continued) 


Parameter ID 


Meaning 


NMA$C_PCLI_CRC! 


NMA$C_PCLI_DES 


Cyclic redundancy check (CRC) generation state for transmitted messages 
(optional). One of the following values can be specified: 


NMA$C_STATE_ON — Controller generates a CRC (default). 
NMA$C_STATE_OFF — Controller does not generate a CRC. 


NMA$C_PCLI_CRC affects all ports on a single controller. There is no effect 
on 


checking a receive message’s CRC (it is always checked). 
NMA$C_PCLI_CRC is passed as a longword value. 


If NMA$C_PCLI_CRC is turned off, all users of the controller must supply 
the 4-byte CRC value for all messages transmitted. The CRC is passed at 
the end of the P1 transmit buffer; the additional 4 bytes are included in the 
size of the P1 buffer. The CRC value is not checked for correctness. 


For the DEQNA, DELQA, and Token Ring devices, the NUA$C_PCLI_CRC 
parameter cannot be turned off. 


For the DEQNA, DELQA, and Token Ring devices, the NUA$C_PCLI_CRC 
parameter cannot be turned off. 


Not all devices support user-supplied CRC. If a controller-generated CRC is 
specified, the request is completed with SS$_BADPARAM status. 


Shared protocol destination address. Passed as a counted string that 
consists of a modifier word (NMA$C_LINMC_SET or 
NMA$C_LINMC_CLR) followed by a 6-byte (48-bit) physical destination 
address. The size of the counted string must always be 8. 
NMA$C_PCLI_DES only has meaning when protocol access 
(NMA$C_PCLI_ACC) is defined as shared-with-destination mode (NMA$C_ 
ACC_LIM). The destination address specified must be a physical 
address—not a multicast address—and it must be unique among all ports 
sharing the same protocol. NUA$C_PCLI_DES is required when the access 
mode is defined as “shared-with-destination.” 


NMA$C_PCLI_DES should not be specified on a port where the 802 or 802E 
packet format is selected (NMA$C_PCLI_FMT is set to 
NMA$C_LINFM_802 or NMA$C_LINFM_802E). For 802 packet format, the 
concept of shared protocol type is handled by using group SAPs. 


NMA$C_PCLI_DES should not be specified on a port where the 802 packet 
format is selected (NMA$C_PCLI FMT is set to NMA$C_LINFM_ 802). For 
802 packet format, the concept of shared protocol type is handled by using 
group SAPs. 


Section 9.4.8 provides a description of protocol type sharing. 


Section 9.4.8 provides a description of protocol type PID sharing. 
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Table 9-39 P2 Attributes (Continued) 


Parameter ID 


Meaning 


NMA$C_PCLI_ EKO! 


NMA$C_PCLI_FMT 


Echo mode. Applicable only to the DEUNA device driver. 


If echo mode is on, transmitted messages are returned to the sender. This 
optional parameter controls the condition of the half-duplex bit in the 
DEUNA mode register. One of the following values can be specified: 


NMA$C_STATE_OFF — Does not echo transmit messages (default) 
NMA$C_STATE_ON — Echoes transmit messages 


If NMA$C_STATE_ON is specified, the only transmitted messages echoed 
are those acceptable to the DEUNA as receive messages, that is, those 
messages that have at least one of the following characteristics: 


e Matching physical address (see Section 9.4.5) 
e Matching multicast address (see Section 9.4.5) 
e Promiscuous mode (NMA$C_PCLI PRM) is in the ON state 


e Destination address is a multicast address and all multicasts are 
enabled (NMA$C_PCLI MLT is in the ON state) 


If the DEUNA is placed in loopback mode (NMA$C_LINCN_LOO is 
specified in the NUA$C_PCLI_CON parameter), the driver enables echo 
mode. 


NMA$C_PCLI_EKO affects all ports on a single controller. It is passed as a 
longword value. 


Packet format. This optional parameter specifies the packet format as either 
Ethernet, IEEE 802, or 802 extended. This characteristic is passed as a 
longword value and affects single ports on a single controller. One of the 
following values can be specified: 


NMA$C_LINFM_ETH — Ethernet packet format (default) 
NMA$C_LINFM_802 — 802 packet format 
NMA$C_LINFM_802E — 802 extended packet format 


NMA$C_PCLI_PTY, NMA$C_PCLI_ACC, and NMA$C_PCLI_DES should 
only be specified on those ports where the Ethernet packet format 
(NMA$C_LINFM_ ETH) is selected. 


NMA$C_PCLI_SRV, NMA$C_PCLI_SAP, and NMA$C_PCLI_GSP should 
only be specified on those ports where the 802 packet format 
(NMA$C_LINFM_ 802) is selected. 


NMA$C_PCLI_PID should only be specified on those ports where the 802 
extended packet format (NMA$C_LINFM_802E) is selected. 


381 


Local Area Network (LAN) Device Drivers 


LAN Function Codes 


Table 9-39 P2 Attributes (Continued) 


Parameter ID 


Meaning 


NMA$C_PCLI_GSP 


NMA$C_PCLI_ILP! 


Group SAP. This is an optional parameter if the 802 packet format is 
selected (NMA$C_PCLI_FMT is set to NUA$C_LINFM_802). If the 
Ethernet or 802 extended packet format is selected, NUA$C_PCLI_GSP 
cannot be specified. Group SAPs can be shared among multiple ports on the 
same controller. If the 802 packet format is selected, NMA$C_PCLI_GSP 
defines up to four 802 group SAPs that are to be enabled for matching 
incoming packets to complete read operations on this port. By default, no 
group SAPs are enabled. 


NMA$C_PCLI_GSP is passed as a longword value and is read as four 8-bit 
unsigned integers. Each integer must be either a group SAP or zero. To 
enable a single group SAP on a port, you need only specify the group SAP 
value to be enabled in one of the four integers and place a value of zero in 
the three remaining integers. To disable group SAPs on the port, you need 
only place a value of zero in all four integers and issue the QIO. 


If this characteristic is correctly specified, any group SAPs that were 
previously enabled on the port are now replaced by the SAPs specified by 
the current request. 


Internal loopback mode. This optional parameter places the device in 
internal loopback mode (not for the DEUNA, DEQNA, or DELQA devices). 
One of the following values can be specified: 


NMA$C_STATE_ON — Internal loopback mode 
NMA$C_STATE_OFF — Not in internal loopback mode (default) 


If NMA$C_STATE_ON is specified, the NUA$C_PCLI_CON parameter 
must be in loopback (NMA$C_LINCN_LOO) mode. 


When the controller is in loopback mode (generally for testing), it can loop 
packets in external loopback or internal loopback. This parameter places the 
controller in one of these loopback modes. NUA$C_PCLI_ILP is passed as a 
longword value and affects all ports on the controller. 


Not all devices support loopback mode. If NMA$C_STATE_OFF is not 
specified, the request is completed with SS$_BADPARAM status. 
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Table 9-39 P2 Attributes (Continued) 


Parameter ID 


Meaning 


NMA$C_PCLI_MCA 


NMA$C_PCLI_MLT 


Multicast address (optional). Passed as a counted string that consists of a 
modifier word followed by a list of 6-byte (48-bit) multicast addresses. The 
value specified in the modifier word determines whether the addresses are 
set or cleared. If NUA$C_LINMC_CAL is specified, all multicast addresses 
in the list are ignored. 


The following mode values can be specified in the low byte of the modifier 
word: 


NMA$C_LINMC_SET — Set the multicast addresses. 
NMA$C_LINMC_CLR — Clear the multicast addresses. 
NMA$C_LINMC_CAL — Clear all multicast addresses. 


The driver filters all multicast addresses on a per-port basis; therefore, only 
messages received with the port's physical address or the multicast 
addresses enabled on the port are used to complete the user's read 
operations. 


Note that each LAN controller supports a limited number of multicast 
addresses. If this limit is exceeded, the LAN driver enables the “accept all 
multicast” feature on the controller and all multicast packets on the LAN 
must be filtered by the LAN driver. This may cause a minor performance 
loss. 


NMA$C_PCLI_MCA is specified on a per-port basis. 


Multicast address state. This optional parameter instructs the controller 
hardware whether to accept all multicast addresses for this port. One of the 
following values can be specified: 


NMA$C_STATE_ON — Accept all multicast addresses. 
NMA$C_STATE_OFF — Do not accept all multicast addresses (default). 


NMA$C_PCLI_MLT allows you to receive all multicast address packets that 
also match the port's protocol type, SAP, or protocol identifier. 


Generally, you enable only your individual set of multicast addresses using 
the NMA$C_PCLI_MCA parameter, and leave the NMA$C_PCLI_MLT 
parameter in the off state. 


There could be a minor performance loss when the NUA$C_PCLI_MLT 
parameter is in the ON state because the LAN driver may have to process 
all multicast addresses on the medium; the number of multicast addresses 
on the line determines the amount of processing required. 


The NMA$C_PCLI_MLT parameter is passed as a longword value. 
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Table 9-39 P2 Attributes (Continued) 


Parameter ID 


Meaning 


NMA$C_PCLI_PAD 


NMA$C_PCLI_PHA! 


Use message size field on transmit and receive messages (optional). One of 
the following values can be specified: 


NMA$C_STATE_ON — Insert message size field (default) 
NMA$C_STATE_OFF — No size field 


NMA$C_PCLI_PAD affects only the protocol type that issued the set mode 
request. It is passed as a longword value. 


On Ethernet, if padding is enabled on Ethernet format packets, the driver 
adds a 2-byte count field to the transmitted data. This field allows short 
packets (packets fewer than 46 bytes long) to be received with the proper 
length returned by the driver. The minimum Ethernet packet contains 46 
bytes of user data. When fewer than 46 bytes are sent, the packet is padded 
and the receiver always receives 46 bytes of data. When padding is enabled, 
the maximum message size for transmit or receive operations is 1498 bytes 
and the minimum is zero bytes. See Section 9.4.6.5.1 for additional 
information. NUA$C_PCLI_PAD should be specified only on a port where 
the Ethernet packet format is selected (NMA$C_PCLI_FMT is set to 
NMA$C_LINFM_ETH). 


For FDDI, the same 2-byte count field is added; however, because FDDI 
packets can be as short as 22 bytes, FDDI transmit requests are never 
padded. 


Physical address (optional). It is passed as a counted string that consists of a 
modifier word followed by the 48-bit physical address. If the request is to 
clear the physical address or to set the physical address to the default 
address, the physical address (if present) is not read. 


One of the following mode values can be specified in the low byte of the 
modifier word: 


NMA$C_LINMC_SET — Set the string value. 

NMA$C_LINMC_CLR — Clear the physical address. 

NMA$C_LINMC_SDF — Set the physical address to the default address. For 
CSMA/CD, the default address is constructed by appending the low-order word of 
the system parameter SCSSYSTEMID to the constant DECnet header 
(AA-00-04-00). If SCSSYSTEMID is zero, and NUA$C_LINMC_SDF is specified, 
the hardware address is used as the default. 


If not specified for Ethernet, the default is the current address set by a 
previous set mode function on this controller, or the hardware address if no 
address was defined by a previous set mode function. If not specified for 
FDDI, the default is the hardware address. 


The physical address must be passed as a 6-byte (48-bit) quantity. The first 
byte is the least significant byte. A return value of -1 on a sense mode 
request implies that a physical address is not defined. 


The NMA$C_PCLI_PHA parameter affects all ports on a single controller. If 
the address specified is already being used on the extended LAN, 
SS$_IVADDR is returned. 
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Table 9-39 P2 Attributes (Continued) 


Parameter ID 


Meaning 


NMA$C_PCLI_PID 


NMA$C_PCLI_PRM 


NMA$C_PCLI_PTY 


Protocol identifier. This parameter is required for, and valid only on, ports 
that use 802 extended format packets. NMA$C_PCLI_PID is passed as a 
counted 5-byte string, which is the unique protocol identifier required for 
each 802 extended format user. 


All protocol identifiers specified on a controller must be unique except when 
the PID is being shared. 


NMA$C_PCLI_PID may only be specified on a port when the 802 extended 
packet format is selected; that is, NMA$C_PCLI_FMT is set to 
NMA$C_LINFM_802E. 


Promiscuous (optional). One of the following values can be specified: 
e NMA$C_STATE_ON—Promiscuous mode enabled. 

e NMA$C_STATE_OFF—Promiscuous mode off. 

The NMA$C_PCLI_PRM parameter is passed as a longword value. 


Only one port on each controller can be active with promiscuous mode 
enabled. Enabling promiscuous mode requires PHY_IO privilege. 


THe NMA$C_PCLI_PRM parameter is passed as a longword value. 
HP does not recommend promiscuous mode for normal usage. 
Some Token Ring devices do not support real promiscuous access to the ring. 


See Section 9.8.1 for additional information. 


Protocol type. This value is read as a 16-bit unsigned integer and must be 
unique on the controller except when the protocol type is being shared. For 
Ethernet format ports, this is a required parameter. 


Valid protocol types are in the range 05-DD through FF. 


NMA$C_PCLI_PTY may only be specified on a port where the Ethernet 
packet format is selected (NMA$C_PCLI_FMT is set to 
NMA$C_LINFM_ETH). 


NMA$C_PCLI_PTY is passed as a longword value; however, only the 
low-order word is used. 
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Table 9-39 P2 Attributes (Continued) 


Parameter ID 


Meaning 


NMA$C_PCLI_RAC 


NMA$C_PCLI_RES 


Receive access control (Token Ring only). This optional parameter specifies 
whether the application receives a copy of the access control (AC) field for 
each Token Ring frame received. It is passed as a longword value. It must be 
passed with one of the following values: 


¢ NMA$C_STAT_ON — Application gets a copy of the AC for each Token 
Ring frame received. 


¢ NMA$C_STATE_OFF — Application does not get a copy of the AC for 
each Token Ring frame received. 


The AC is returned in the P5 buffer. The P5 buffer size for Token Ring 
should always be a minimum of 54 bytes. This is due to the variable size of 
the Token Ring header. 


Restart. This optional parameter allows the user to enable the automatic 
port restart feature of the LAN drivers. One of the following values can be 
specified: 


e NMA$C_LINRES_DIS — Disable automatic restart (default) 
e NMA$C_LINRES_ENA — Enable automatic restart 


The LAN drivers shut down all users of a controller if there is a fatal error 
on the controller or if the LAN driver determines that the controller has 
stopped functioning. All outstanding I/O operations on the LAN driver are 
completed with either an SS$_ABORT or SS$_TIMEOUT status. 


All ports that have the NMA$C_PCLI_RES parameter enabled (set to 
NMA$C_LINRES_ENA) have the port automatically restarted by the LAN 
driver approximately one second after it has been shut down due to a fatal 
error. If the user issues read or write QIOs to the port during the time the 
port is shut down, the driver completes the QIOs with an SS$_OPINCOMPL 
status. 


All ports that have the automatic restart feature disabled must be restarted 
by the application program when the port is shut down by the LAN driver. 
The application program should wait approximately 2 seconds to allow the 
LAN driver to stabilize. Once the LAN driver shuts down a port, it attempts 
a maximum of 30 consecutive automatic restarts. If there are 30 consecutive 
failures to restart the port, the port remains shut down. 


Note that it is unusual to have fatal errors on a LAN controller or to have a 
LAN driver detect that a LAN controller has stopped functioning. Having 
the ability to automatically restart a user's port makes the program easier 
to design because the program does not have to take into account the 
possibility of the LAN driver shutting down the port. 
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Table 9-39 P2 Attributes (Continued) 


Parameter ID 


Meaning 


NMA$C_PCLL_RFC 


NMA$C_PCLI_SAP 


Receive frame control (FDDI only). This optional parameter specifies 
whether the application receives a copy of the Frame Control (FC) field for 
each FDDI frame received. It is passed as a longword value. However, only 
the low-order byte is used. It must be passed with one of the following 
values: 


¢ NMA$C_STATE_ON — Application gets a copy of the FC for each FDDI 
frame received. 


¢ NMA$C_STATE_OFF — Application gets a copy of the FC for each 
FDDI frames (default). 


For $QIO Read operations, the FC is passed to the application in the P5 
buffer. The following are the sizes required for the P5 buffer for various 
packet formats and settings of NUA$C_PCLI_RFC: 


e Ethernet (NMA$C_LINFM_ETH) — 14 if NMA$C_STATE_OFF is 
specified, 15 if NUA$C_STATE_ON is specified. 


¢ 802 (NMA$C_LINFM_802) — 16 if NMA$C_STATE_OFF is specified, 
17 if NMA$C_STATE_ON is specified. 


e 802E (NMA$C_LINKFM_802E) — 20 if NMA$C_STATE_OFF is 
specified, 21 if NUA$C_STATE_ON is specified. 


Receiving the FC requires one additional byte of space in the P5 buffer. 
The FC is the first byte in the P5 buffer, immediately preceding the 
6-byte destination address. The size of the P5 buffer required does not 
change from the CSMA/CD sizes if NUA$C_PCLI_RFC is set to 
NMA$C_STATE_OFF. 


802 format SAP. This parameter is required if the 802 packet format is 
selected (NMA$C_PCLI FMT is set to NMA$C_LINFM_802)> 
NMA$C_PCLI_SAP defines an 802 SAP and is read as an 8-bit unsigned 
integer. The least significant bit of the SAP must be 0 and the SAP cannot be 
the null SAP (all 8 bits equal 0) or the SNAP SAP. NMA$C_PCLI_SAP is 
passed as a llongwood value. However, only the low-order byte is used. 


The SAP specified by NUA$C_PCLI_SAP is the SAP used to match 
incoming packets to complete read requests. It is used as the source SAP 
(SSAP) in all transmissions (write QIOs). Because it is illegal to transmit 
using a group SAP as the source SAP, the SAP specified by this 
NMA$C_PCLI_SAP cannot be a group SAP. NMA$C_PCLI_GSP describes 
how to set up group SAPs on a port. 


All individual SAPs specified on a controller must be unique on that 
controller; therefore, the SAP specified using the NMA$C_PCLI_SAP 
parameter is checked for uniqueness on the controller. 
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Parameter ID 


Meaning 


NMA$C_PCLI_SRMODE 


NMA$C_PCLI_SRV 


NMAC$C_PCLI_XAC 


NMA$C_PCLI_XFC 


Sets the source routing (SR) modefor the $QIO user (Token Ring only). This 
optional parameter allows the application to perform the source routing 
discovery. It must be passed with one of the following values: 


¢ NMA$C_SR_TRANSPARENT — Application source routing is 
transparent. This is the default when this parameter is not specified. 


¢ NMA$C_SR_SELF — This shuts off the automatic route discovery 
exploration messagefor this user. 


The $QIOs existto further manipulate the source routing cache. HP 
recommends that applications use the NUA$C_SR_TRANSPARENT mode. 


Port service. This optional parameter specifies the service supplied by the 
driver for the port. It can only be specified if the 802 packet format is 
selected (NMA$C_PCLI_FMT is set to NUA$C_LINFM_802). This 
characteristic is passed as a longword value. One of the following values can 
be specified: 


¢ NMA$C_LINSR_USR — User supplied service (default) 
e NMA$C_LINSR_CLI — Class I service 


Transmit access control (Token Ring only). This is an optional parameter 
that enables applications to contol the setting of the priority bits in the 
access control (AC) for frames being transmitted in a $QIO write operations. 
When set to a wanted value, all subsequent transmits use this AC value. 


Transmit frame control (FDDI) only). NMA$C_PCLI_XFC is an optional 
parameter that enables applications to control the setting of the priority bits 
in the FC for frames being transmitted in a $QIO write operation. 
NMA$C_PCLI_XFC is passed as a longword parameter that has many valid 
settings. If specified with a value of 0, the application supplies an FC value 
on each $QIO write operation. The FC value to be used in this case is 
supplied in the P5 buffer for the $QIO write operation. If the parameter is 
specified with a value other than 0, that value is inserted into the FC field of 
every transmit by the FDDI drivers. NO FC is present in the P5 buffer for 
the $QIO write in this case. If this parameter is not specified, the default 
setting (0) of the priority bits is used. 


Regardless of how the FC is supplied, the value specified must be valid. The 
allowable values for FC are between 50 hexadecimal and 57 hexadecimal. If 
NMA$C_PCLI_XFC is specified with a nonzero value outside the valid 
range, the application receives a SS$_ BADPARAM error. The priority bits 
are the three low-order bits. 


1. If the LAN controller is active and you do not specify this parameter, the parameter defaults to 
current setting. If the LAN controller is not controller is not active, this parameter defaults to the 


default value indicated. 
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9.7.3.2 Set Mode Parameters for Packet Formats 


Table 9-40 summarizes the use of the set mode parameters for the Ethernet, 802, and 802 extended (802E) 
packet formats. 


Table 9-40 Set Mode Parameters for Packet Formats 
Parameter ID Ethernet IEEE 802 802E 
FMT DEF REQ REQ 
PTY REQ E E 
SAP E REQ E 
PID E E REQ 
ACC OPT E 
DES OPT E 
PAD OPT E E 
SRV E OPT E 
GSP E OPT E 
BFN, BUS, CCA, CON, OPT OPT OPT 


CRC, EKO, ILP, MCA, 
MLT, PHA, PRM, RAC, 
RES, RFC, SRMODE, 
XAC, XFC 


9.7.3.3 Set Mode Parameter Validation 


When starting a LAN port, the LAN driver checks that the mode of the new port is compatible with the mode 
of the LAN ports already started. There are two sets of compatibility checks: one for ports running in shared 
mode and one for all ports. 


The following parameters must match for all ports on the same controller: 
¢ NMA$C_PCLI_CON 

¢ NMA$C_PCLI_CRC 

¢ NMA$C_PCLI_EKO 

¢ NMA$C_PCLI_ILP 

¢ NMA$C_PCLI_PHA (need only match for Ethernet controllers) 


On VAX systems, the following parameters must match for all shared-default and shared-with-destination 
users of the same protocol type: 


e NMA$C_PCLI_BFN 
¢ NMA$C_PCLI_BUS 
e NMA$C_PCLI_CCA 
e NMA$C_PCLI_MLT 
¢ NMA$C_PCLI_PAD 
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¢ NMA$C_PCLI_PTY 
e NMA$C_PCLI_RAC 
e NMA$C_PCLI_RES 
¢ NMA$C_PCLI_RFC 
¢ NMA$C_PCLI_XAC 
e NMA$C_PCLI_XFC 


Once a port is started, only the following parameters can be changed: 


¢ NMA$C_PCLI_GSP 
¢ NMA$C_PCLI_MCA 


9.7.4 Shutdown Controller 


The shutdown controller function shuts down the LAN port. On completion of a shutdown request all 
outstanding I/O requests are completed. This port cannot be used again until another startup request has 
been issued (see Section 9.7.3.1 ). 


The following function code is used to shut down a port: 
¢ I0$_SETMODE!IO$M_CTRL!IO$M_SHUTDOWN—Shut down port 


The shutdown controller function takes no device- or function-dependent arguments. 


9.7.5 Enable Attention AST 


This function requests that an attention AST be delivered to the requesting process when a status change 
occurs on the assigned port. An AST is queued when a message is available and there is no waiting read 
request. The enable attention AST function is legal at any time, regardless of the condition of the unit status 
bits. 


The following function code and modifier is used to enable an attention AST: 
¢ I0$_SETMODE!IO$M_ATTNAST—Enable attention AST 

This function takes the following device- or function-dependent arguments: 
e P1—The address of an AST service routine or 0 for disable 

e P2—Ignored 

e P38—Access mode to deliver AST 


The enable attention AST function enables an attention AST to be delivered to the requesting process once 
only. After the AST occurs, it must be explicitly reenabled by the function before the AST can occur again. The 
function is subject to AST quotas. 


The AST service routine is called with an argument list. The first argument is the current value of the second 
longword of the I/O status block (see Section 9.7.18). 


390 


Local Area Network (LAN) Device Drivers 
LAN Function Codes 


9.7.66 IO0$M SET MAC Functional Modifier to IO$¢M SETMODE 


The IO$M_SET_MAC qualifier, when used with IO$_SETMODE, is used to set medium specific parameters. 
The Token Ring parameters require PHY_IO privilege to be set. Table 9-41 shows the parameters that may be 
set for Ethernet. Table 9-42 shows the parameters that may be set for FDDI. Table 9-43 shows the 
parameters that may be set for Token Ring, and Table 9-44 shows the parameters that may be set for ATM. 


Table 9-41 Parameters of IO$M_SET_MAC for Ethernet 
Parameter ID Meaning 
MA$C_PCLI_FDE Enables or disables full duplex operation. The values for this parameter 


are NMA$C_STATE_ON or NMA$C_STATE_OFF. 


NMA$C_PCLI_LLINEMEDIA _ Sets the connection media type for the Ethernet adapter. Valid values for 
this parameter are: 


¢ NMA$C_MEDIA_AUTO 
¢ NMA$C_MEDIA_AUI 

e NMA$C_MEDIA_BNC 

¢ NMA$C_MEDIA_TP 


NMA$C_PCLI_LINESPEED Sets the speed of the Ethernet adapter. Valid values for this parameter 
are: 


e 0—Used to autosense the speed. 

e 10—Sets the speed to 10 megabits/second. 

e 100—Sets the speed to 100 megabits/second. 

e 1000—Sets the speed to 1000 megabits/second. 


391 


Local Area Network (LAN) Device Drivers 
LAN Function Codes 


Table 9-42 Parameters of IO$M_SET_MAC for FDDI 


Parameter ID 


Meaning 


NMA$C_PCLI_TREQ 


NMA$C_PCLI_TVX 


NMA$C_PCLI_REST_TTO 


NMA$C_PCLI_RPE 


NMA$C_PCLI_NIF_TARG 
NMA$C_PCLI_SIF_CONF_TARG 


NMA$C_PCLI_SIF_OP_TARG 


NMA$C_PCLI_ECHO_TARG 


NMA$C_PCLI_ECHO_DAT 
NMA$C_PCLI_ECHO_LEN 


Requested value for token rotation timer, ANSI MAC T_req 
parameter. Units are in 80 nanoseconds, the default is 8000, minimum 
is 4000, and maximum is 167772. 


Maximum time between arrivals of a valid frame or unrestricted 
token, ANSI MAC TVX parameter. Units are in 80 nanoseconds, the 
default is 2621, minimum is 2500, and maximum is 5222. 


Restricted token timeout which limits how long a single restricted 
mode dialog may last before being terminated. Units are in 
milliseconds, the default is 1000, minimum is 0, and maximum is 
10000. 


Ring purge enable. If 1 (TRUE), this link will particpate in the Ring 
Purger election and, if elected, perform the Ring Purger function. 


Neighbor information frame target. 


Station information frame configuration target. A 6-byte string 
specifying the LAN address of the target. Used only by DECnet/OSI. 


Station information frame operation target. A 6-byte string specifying 
the LAN address of the target. Used only by DECnet/OSI. 


Echo test target. A 6-byte string specifying the LAN address of the 
target. Used only by DECnet/OSI. 


Data pattern to use for the echo test. Used only by DECnet/OSI. 
Length of the echo packet. Used only by DECnet/OSI. 


Table 9-43 Parameters of IO$M_SET_MAC for Token Ring 


Parameter ID 


Meaning 


NMA$C_PCLI_RNG_SPD 


NMA$C_PCLI_LINEMEDIA 
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Sets the speed of the ring. This longword may be either: 
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Table 9-43 Parameters of IO$M_SET_MAC for Token Ring (Continued) 


Parameter ID 


Meaning 


NMA$C_PCLI_ETR 


NMA$C_PCLI_MONCONTEND 


NMA$C_PCLI_CACHE_ENT 


NMA$C_PCLI_ROUTEDIS 


NMA$C_PCLI_A_TIM 


NMA$C_PCLI_SRC_ROU 


NMA$C_PCLI_AUTH_PR 


Controls the Early Token release feature of the Token Ring hardware. 
This feature can greatly improve throughput, and is only valid on 16 
Mb/s rings. The values for this longword parameter are 
NMA$C_STATE_ON or NMA$C_STATE_OFF. The default is 
NMA$C_STATE_ON. 


Specifies whether the controller participates in the monitor contention 
process when another adapter detects the need for contention and 
initiates the process. The values for this longword parameter are 
NMA$C_STATE_ON or NMA$C_STATE_OFF. The default is 
NMA$C_STATE_OFF. 


The number of source routing (SR) entries to make available for 
caching. The default is 200, minimum is 20, and maximum is 2000. 
Each cache entry consumes 64 bytes. 


The source routing discovery timer. This is the amount of seconds to 
wait after the transmission of ring explorer packets before declaring 
the route of a path to be unknown. The default is 2 seconds, minimum 
is 1, and maximum is 255. 


The source routing aging timer. After traffic is neither received from 
nor sent to a given node for this number of seconds, the entry is marked 
stale. After the entry is marked stale, rediscovery is required to 
communicate with the node. The default is 60 seconds, minimum is 1, 
and maximum is 65535. 


Enables and disables source routing. The values for this longword 
parameter are NMA$C_LINSRC_ENA or NMA$C_LINSRC_DIS. The 
default is NUA$C_LINSRC_ENA. 


Specifies the highest priority that a user may transmit a frame. The 
priority is set within the NMA$C_PCLI_XAC parameter. The default 
for this parameter is 3, minimum is 0, and maximum is 6. 
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Table 9-44 Parameters of IO$M_SET_MAC for ATM 
Parameter ID Meaning 
NMA$C_PCLI_MED Medium. This longword parameter defaults to and may only be set to 
NMA$C_LINMD_CSMACD. 
NMA$C_PCLI_BUS Buffer size. This longword parameter specifies the requested maximum 
packet size of the emulated LAN. The value may be either 1516, 4544, or 
9234. 


NMA$C_PCLI_LELAN_PAR Parent device name. This is a 3- or 4-character string parameter that 
specifies the name of the ATM device to associate with this emulated 
LAN. 


NMA$C_PCLI_NET ELAN name. This is a string of up to 64 characters that specifies the 
name of the emulated LAN to join. 


NMA$C_PCLI_LELAN_DESC ELAN description. This is a string of up to 64 characters long that 
provides additional description of the emulated LAN for status displays. 


NMA$C_PCLI_LES_HWA LES ATM address. This is specified as a 40-character string as the 
hexadecimal representation of a 20-byte ATM address. 


NMA$C_PCLI_LELAN_STATE ELAN change state request value. This longword parameter directs the 
_REQ driver to either start or shutdown the emulated LAN. Start is specified by 
a value of 2. Shutdown is specified by a value of 4. 


NMA$C_PCLI_LEVENT_REQ Event mask request. If set to 1, this longword parameter directs the 
driver to set the event reporting mask to the value given by the event 
parameter. 


NMA$C_PCLI_EVENT Event mask value. This is a longword bit mask that controls the event 
reporting done by the driver. A bit set in the mask enables the reporting 
of corresponding event(s). 


394 


Local Area Network (LAN) Device Drivers 
LAN Function Codes 


9.7.7 I0$M UPDATE MAP Functional Modifier to IO$ SETMODE 


Using Token Ring only, the IO$M_UPDATE_MAP qualifier, when used with IO$_SETMODE, manipulates 
the adapter's functional address mapping table. Figure 9-15 shows the format of the P2 buffer for this 
operation. This QIO requires PHY_IO privilege. 


Figure 9-15 Format of IO$M_UPDATE_MAP Setmode P2 Buffer 


31 15 0 


Length NMA$C_PCLI_MAP 
(bytes following this field) 


MC Addr 1 Subfunction 


MC Addr 3 MC Addr 2 
FUNCTIONAL Address 2 FUNCTIONAL Address 1 


ZK6791AGE 


The subfunction is one of the following: 


¢ NMA$C_MAP_CHANGE — This function adds or changes a mapping in the functional address table. If 
the specified multicast entry does not exist, an entry is created with the specified functional address 
mask. If the specified multicast entry does exist, the corresponding functional address mask is changed to 
the specified mask. All users who currently have the multicast enabled when the functional mask is 
changed will automatically update the functional address table as part of this operation. 


Possible errors returned include the following: 


— SS$_DEVICEFULL — This error indicates that there is insufficient space in the mapping table to 
complete the request. The multicast to functional address mapping table has 200 entries. 


¢ NMA$C_MAP_DELETE — This function deletes the specified MC address in the table. For this function, 
the functional address mask is not required to pass the P2 buffer. If the functional address mask is 
passed, its contents are ignored. 


Possible errors returned include the following: 


— SS$_BADPARAM — This error indicates that the specified multicast address cannot be found in the 
table. 


The following example maps multicast address AB-01-01-01-02-03 to the functional address 
03-00-00-01-00-00 for device ICAO:. 


LANCP>SET DEVICE/MAP= — 
_LANCP> (MULTICAST=AB-01-01-01-02-03, —- 
_LANCP>FUNCTIONAL=00-01-00-00) ICAO: 


The following example deletes the mapping of the multicast address of AB-01-01-01-02-03 for the device 
ICAO:. 


LANCP>SET DEVICE/NOMAP= (MULTICAST=AB-01-01-01-02-03) ICAO: 
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9.7.88 IO$M ROUTE Functional Modifier to IO$¢ SETMODE 


For Token Ring only, the IO$M_ROUTE qualifier, when used with IO$_SETMODE, manipulates the source 
routing cache table. This command is successful only when source routing is enabled. Source routing is 
enabled with the set mac qualified set mode QIO. Figure 9-16 shows the format of the P2 buffer. This QIO 
requires the PHY_IO privilege. 


31 15 
Length NMA$C_PCLI_MAP 
(bytes following this field) 
MC Addr 1 Subfunction 
MC Addr 3 MC Addr 2 
Routing Information String RI_Size 
030 bytes. 


Figure 9-16 Format of the IO$M_ROUTE P2 Buffer 
0 


ZK6792AGE 


The subfunction is one of the following: 


¢ NMA$C_SR_ADD — This function adds or changes a source routing cache entry. It enters the LAN 
address into the table with the enclosed routing information. The routing information string format is 
documented in Section 9.4.6.3 I. If RI_size is passed as 0, the entry is created (or modified) to be in the 
EXPLORING state (this is useful for users who are doing their own source routing). If the RC 'Lth' field is 
0, the LAN address is entered in the table as being in the local state. 


Possible errors returned include: 

— SS$_INSFMEM — The source routing cache is full. 

— SS$_BADPARAM — An invalid RI string was passed or invalid sizes were passed. 
— SS$_IVMODE — Source routing is not enabled. 


¢ NMA$C_SR_DELETE — This function deletes a source routing cache entry. The RI_size and the routing 
information string are not required for this QIO. If one or both of the fields are passed for this operation, 
they are ignored. The result of this command is to put the entry into the deleted state. When the entry 
goes into the deleted state, it is deleted within 10 minutes. 


Possible errors returned include the following: 


— SS$_BADPARAM — The requested entry could not be found. 
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9.7.9 Sense Mode and Sense Characteristics 


The sense mode function returns the port attributes in the specified buffers. These attributes include the 
device characteristics described in Section 9.6 and, with the exceptions noted below, the attributes listed in 
Table 9-39. 


The following combinations of function code and modifier are provided: 


IO$_SENSEMODE!IO$M_CTRL—Read characteristics 
I0$_SENSECHARIIO$M _CTRL—Read characteristics 
10$_SENSEMODE!IO$M_SENSE_MAC—Medium specific characteristics 


I0$_SENSEMODE!IO$M_SHOW_MAP—Returns current functional address to multicast address 
mapping (Token Ring only) 


10$_SENSEMODE!IO$M_SHOW_ROUTE—Returns current source routing cache table (Toekn Ring 
only) 


These functions take the following device- or function-dependent arguments: 


P1—The address of a two-longword buffer where the device characteristics are stored. (Figure 9-17 shows 
the format for, and Section 9.6 describes the contents of, the P1 buffer.) The P1 argument is optional. 


P2—The address of a quadword descriptor where the attributes buffer is stored. The first longword of the 
descriptor is the buffer length; the second longword is the address of the buffer. The P2 argument is 
optional. 


The P2 buffer is not read by the LAN driver. The driver stores the port's attributes in the buffer, which 
contains multiple entries. The format of each entry depends on whether a longword or a counted string is 
returned, as shown in Figure 9-18. Each parameter ID contains a string indicator bit (bit 12) that 
describes whether the data item is a string or a longword. 


Except for the following differences, P2 returns the same attributes as those listed in Table 9-37: 


All parameters that are valid for the enabled packet format are returned (see Table 9-38). 


The sense-mode P2 buffer does not return the modifier word for the NUA$C_PCLI_PHA, 
NMA$C_PCLI_MCA, and NMA$C_PCLI_DES parameter IDs. 


The NMA$C_PCLI_DES parameter is only returned on Ethernet ports whose access mode is set to 
“shared with destination.” 
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e In addition to the parameter IDs listed in Table 9-37, the sense-mode P2 buffer contains the following 
parameter IDs:! 


Parameter ID Meaning 


NMA$C_PCLI_FCA List of the currently enabled functional addresses (Token Ring only). Each 
32-bit entry corresponds respectively with the items returned under 
NMA$C_PCLI_MCA. 


NMA$C_PCLI_HWA Hardware address. Describes the value for the hardware address. The 
hardware address is the default physical address when no physical 
address has been specified and there are no active users on the controller. 
NMA$C_PCLI_HWA is returned in the same format as 
NMA$C_PCLI_PHA. 


NMA$C_PCLI_MBS Maximum packet length. NMA$C_PCLI_MBS is a longword, read-only 
parameter. The value returned reflects the largest data packet that the 
application can receive for its packet format and type of LAN, measured in 
bytes. The values for Ethernet, FDDI, and Token Ring are: 


Packet Format Ethernet FDDI Tok aa 
Ring 
Ethernet format without 1500 4470 4418 
padding 
Ethernet format with padding 1498 4468 4416 
802 format with 1-byte CTL 1497 4475 4423 
field 
802E format 1492 4470 4418 
The values for LAN emulation over ATM are: 
Packet Format ATM 1516 4544 9234 
ELAN 
size: 
Ethernet format without 1500 4528 9218 
padding 
Ethernet format with padding 1498 4526 9216 
802 format with 1-byte CTL 1497 4525 9215 
field 
802E format 1492 4520 9210 


1. Alpha specific. 
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Figure 9-17 Sense Mode P1 Characteristics Buffer 
31 24 23 1615 8 7 0 


ZK1178GE 


It is suggested that a size of 250 bytes be used for the P2 buffer. This will allow space for additional 
parameters that may be returned in future releases of OpenVMS. 


All attributes that fit into the buffer specified by P2 are returned; however, if all the attributes cannot be 
stored in the buffer, the I/O status block returns the status SS$_ BUFFEROVF. The second word of the I/O 
status block contains the number of bytes used in the P2 buffer (see Section 9.7.13). 


Figure 9-18 Sense Mode Attribute Buffer 


Longword Parameter: 


1514 1312 11 


jo] = fol Parameter ID 


Longword of 


Value 


* Not Used 
String Parameter: 
1514 1312 11 


jo] = fa] Parameter ID 
Word of String Count 


* Not Used 


ZK1210GE 


399 


Local Area Network (LAN) Device Drivers 
LAN Function Codes 


9.7.10 IO$M SENSE MAC Functional Modifier to IO$ SENSEMODE 


The IO$M_SENSE_MAC qualifier, when used with I0$_SENSEMODE, returns the parameters specified in 
Section 9.7.6. In addition to the set mac parameters, Table 9-45 shows the returns of the following 
parameters: 


Table 9-45 Parameters of IO$M_SENSE_MAC 
Parameter ID Meaning 
NMA$C_PCLI_T_NEG The negotiated value of the token rotation timer (ANSI MAC parameter 
T_neg) (FDDI only). 
NMA$C_PCLI_DAT The duplicate address test flag (FDDI only). If set, this indicates that 
there is another station on the ring with the same hardware LAN address. 
NMA$C_PCLI_UNA Upstream neighbor's address (FDDI and Token Ring). This is a string 


parameter specifying the 6-byte LAN address of the upstream neighbor. 
Not all devices may support this feature. 


NMA$C_PCLI_LOLD_UNA The old (previous) upstream neighbor address (FDDI only). Neighbor 
addresses change as nodes insert and deinsert into the ring. 
NMA$C_PCLI_LUN_DAT The upstream neighbor's duplicate address test flag (FDDI only). 
NMA$C_PCLI_DNA The downstream neighbor's LAN address (FDDI only). 
NMA$C_PCLI_LOLD_DNA The old (previous) downstream neighbor's LAN address (FDDI only). 
NMA$C_PCLI_RPS The current ring purger state (FDDI only). This longword parameter is 
one of the following values: 
¢ 0— Off 


e 1— Candidate 
e 2—Non-purger 
e 3— Purger 
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Table 9-45 Parameters of IO$M SENSE_MAC (Continued) 


Parameter ID 


Meaning 


NMA$C_PCLI_RER 


NMA$C_PCLI_NBR_PHY 


The latest ring error reason (FDDI only). This longword parameter is one 
of the following values: 


¢ 0—No Error 

e 5— Ring Init initiated 

e 6 — Ring Init received 

e 7— Ring beaconing initiated 

e 8— Duplicate address detected 
e 9— Duplicate token detected 

e 10— Ring purger error 

e 11—FCI strip error 

e 12— Ring op oscillation 

e 14— PC trace initiated 


e 15 — PC trace received 


Neighbor's PHY type (FDDI only). This longword parameter is one of the 
following values: 


e 0O—A 
e 1—B 
e 2—S5 
e 3—M 


e 4— Unknown 
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Table 9-45 Parameters of IO$M SENSE_MAC (Continued) 
Parameter ID Meaning 
NMA$C_PCLI_RJR Ring reject reason (FDDI only). This longword parameter is one of the 


following values: 

¢ 0— None 

e 1—Local LCT 

e 2— Remote LCT 

¢ 3 —LCT both sides 

e 4— LEM reject 

e 5— Topology error 

e 6—Noise reject 

e 7— Remote reject 

e 8— Trace in progress 

e 9— Trace received-disabled 
e 10—Standby 

e 11—LCT protocol error 


NMA$C_PCLI_LEE Link error estimate (FDDI only). The longword value is a negative 
exponent of 10 representing the Link error rate. For example, the value of 
X represents the error rate of 10*X. 


NMA$C_PCLI_LRNG_NUM The longword value contains the ring number that the controller is 
running on (Token Ring only). It is only valid for a controller that is 
started, and also only valid for rings that have a ring parameter server 
that is configured for providing this information. 
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9.7.11 IO0$M SHOW MAP Functional Modifier to IO$ SENSEMODE 


For Token Ring only, the IO$M_SHOW_MAP qualifier, when used with IO$_SENSEMODE, returns the 
current setting of the mapping table. The P2 buffer is filled with the current multicast to functional address 
mapping information. The entries are 16 bytes long and are in the format shown in Figure 9-19. This QIO 
requires PHY_IO privilege. 


Figure 9-19 Format of IO$M SHOW MAP P2 Buffer 
15 


31 0 
Multicast 2 Multicast 1 
Functional address mark 


ZK6793AGE 


The multicast address and functional address mask are returned in canonical format (that is, not 
bit-reversed). The following errors may occur: 


e SS$ _BUFFEROVF — The passed buffer is not large enough to hold all the data required for the 
operation. 


e SS$ BADPARAM — Not able to get read access to buffer or zero length buffer passed. 
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9.7.12 IO0$M_SHOW_ROUTE Functional Modifier to IO$_SENSEMODE 


For Token Ring only, the IO$M_SHOW_ROUTE qualifier, when used with I0$_SENSEMODE, returns the 
current value of the source routing cache table. Each entry is 64 bytes long. Figure 9-20 shows the format of 
the returned P2 buffer. 
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Figure 9-20 Format of IO$M SHOW _ROUTE P2 Buffer 
15 0 


31 

Routing Control Field 
Segment Descriptor 
Segment Descriptor 
Segment Descriptor 
Segment Descriptor 
Segment Descriptor 
Segment Descriptor 


ZK6794AGE 
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Table 9-46 shows possible states of the entry. 


Table 9-46 State of the Entry 
Value Name Description 
0 LOCAL Address is reachable on the attached ring. 
1 STALE Entry is stale (inactive). 
2 UNKNOWN Route to the address is unknown. 
3 DELETED Entry is marked for deletion. 
4 KNOWN Route is known and the route is stored in the routing information 
string. 
5 EXPLORING Route to the address is currently being explored. 


The LAN address is returned in canonical format (that is, not bit-reversed). The timers are recorded as 
seconds before expiration. The transmit and receive timers are initialized from the NUA$C_PCLI_A_TIM 
parameter, the discovery timer is initialized from the NMA$C_PCLI_ROUTEDIS parameter, and the stale 
timer is initialized to 10 minutes (600 seconds). The following errors may occur: 


e SS$ _BUFFEROVF — The passed buffer is not large enough to hold all the data required for the 
operation. 


e SS$ _BADPARAM — Not able to get read access to buffer or zero length buffer passed. 


9.7.13 W/O Status Block 


The I/O status block (IOSB) for all LAN driver functions is shown in Figure 9-21. Appendix A lists the 
completion status returned for these functions. (The OpenVMS system messages documentation provides 
explanations and suggested user actions for these status codes.) 


Figure 9-21 IOSB Contents 


Transfer Size Completion Status 


Not Error Not 


Byte of Value 
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The first longword of the IOSB returns, in addition to the completion status, either the size (in bytes) of the 


data transfer or the size (in bytes) of the attribute buffer (P2) returned by a sense mode function. The second 


longword returns the unit and line status bits listed in Table 9-32 and the error summary bits listed in 
Table 9-33. 
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9.8 Application Programming Notes 


This section contains information to assist you in writing application programs that use the LAN device 
drivers. Section 9.8.1 discusses the additional rules required for application programs that you intend to run 
in promiscuous mode. Section 9.8.2 describe the Ethernet and 802 sample programs. 


9.8.1 Promiscuous Mode 


The LAN drivers allow only one port per controller to enable promiscuous mode (NMA$C_PCLI_PRM 
specified as NMA$C_STATE_ON). A port running in promiscuous mode usually places an additional load on 
the CPU because the LAN device is configured to deliver all received packets to the LAN driver regardless of 
destination address or multicast filtering. The LAN driver then has deliver the packets to the promiscuous 
port as well as a copy to the intended recipient. 


Table 9-47 details additional rules for ports running in promiscuous mode. 


Table 9-47 Rules for Promiscuous Mode Operation 
V/O Function Rule 
10$_SETMODE It is not necessary to specify a unique identifier (a protocol type, SAP, or protocol 
I0$_ SETCHAR identifier parameter ID) in the P2 buffer. 


The port cannot be running in shared mode. 


I10$_WRITE The user can only transmit packets in the packet format previously specified with 
a set mode QIO when the user was started. The unique identifier for the packet 
format must be included in the P5 buffer following the destination address (see 
Section 9.7.2 ). 


I0$_READ The LAN driver completes the promiscuous user's read requests with Ethernet, 
802, and 802 extended packets. Because any packet format can be used to 
complete a read request, the P5 parameter (if specified) must be at least 20 bytes 
in length (21 bytes for FDDI with RFC turned on). 


All Ethernet format packets are processed as if they have no size field specified 
after the protocol type. Therefore, Ethernet packets are always returned with 46 
to 1500 bytes of data. If the Ethernet packet contains a size field, it is returned as 
part of the user data in the first word of the P1 buffer. 


The promiscuous user should use the information returned in the P5 buffer to 
determine the packet format. If the application program first filled the P5 buffer 
with zeros, the program can determine the format of the packet received by 
scanning the P5 buffer after the read request is completed. 


9.8.2 Local Area Network Programming Examples 


The VAX MACRO program LANETH.MAR (Example 9-2 shows the typical use of QIO functions in driver 
operations such as establishing the protocol type, starting the port, and transmitting and receiving data. The 
program sends a LOOPBACK packet and waits for the packet to be returned. 


The HP C program LAN802E.C (Example 9-3 ) shows how to initialize an 802E port and how to send and 
receive packets on that port. This program sends a LOOPBACK packet and waits for the packet to be 
returned. 
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Example 9-2 LANETH.MAR Local Area Network Programming Example 


.TITLE LAN SAMPLE TEST PROGRAM 
-IDENT /X03/ 
.PSECT RWDATA,WRT,NOEXE, PAGE 


; This LAN test program sends a MOP loopback message to the Loopback Assistant 
; Multicast address and waits for a response. The program uses the LAN device 
; EWAO. To use a different device, change the device name in the program or 

; Gefine the desired lan device as EWAO. 


* To build on VAX, Alpha, 164: 
; $ MACRO/OBJECT=LANETH/LIST=LANETH SYSSLIBRARY:ARCH_DEFS.MAR+SYSSDISK: [] LANETH 
; $ LINK LANETH 


5 To run: 
; $ RUN LANETH 


. LIBRARY "SYSSLIBRARY:LIB.MLB" 


SIODEF ; Define I/O functions and modifiers 
SNMADEF ; Define Network Management parameters 
; Setmode parameter buffer and descriptor. Since the loopback protocol does 


; not include a length word following the protocol type, we have to explicitly 
; turn off padding since the default is on. 


SETPARM: 
.WORD NMASC_PCLI_FMT ; Packet format 
. LONG NMASC_LINFM_ETH ; Ethernet 
.- WORD NMASC_PCLI_PTY 7 Protocol type 
. LONG *x0090 ; Loopback 
. WORD NMASC_PCLI_PAD ; Padding 
. LONG NMASC_STATE_OFF 7 oft 
SETPARMLEN = .-SETPARM 
SETPARMDSC: 
. LONG SETPARMLEN 
-ADDRESS SETPARM 
; Sensemode parameter buffer and descriptor. This is used to get our physical 


; address to put into the loopback message. 


SENSEBUF: 
. BLKB 512 
SENSELEN=.-SENSEBUF 


SENSEDSC: 
- LONG SENSELEN 
-ADDRESS SENSEBUF 


; P2 transmit data buffer. 


XMTBUF: .WORD 00 ; Skip count 
.WORD 02 ; Forward request 
FORW: - BLKB 6 ; Forward address 
.- WORD O1 ; Reply request 
.WORD 00 
XMTBUFLEN = .-XMTBUF ; Size of transmit buffer 


; P5 transmit destination address, the Loopback Assistant Multicast Address. 


XMTP5: . BYTE *XCF,0,0,0,0,0 
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; P2 receive data buffer. 


RCVBUF: .BLKB 512 
RCVBUFLEN = .—-RCVBUF ; Size of receive 


; P5 receive header buffer. 


RCVP5: 
RCVDA: - BLKB 6 
RCVSA: . BLKB 6 


RCVPTY: .BLKB 2 


; Messages used to display status of this program. 


GMSG: -ASCID "Successful test" 

LMSG: -ASCID "No response" 

EMSG: -ASCID "Error occurred while running test" 
DMSG: -ASCID "LAN device not found" 


; Miscellaneous data. 


IOSB: . BLKQ 1 ; I/O status block 
DEVCHAN: .BLKL 1 ; Returned port nu 
LANDSC: .ASCID ‘EWAO' ; Device to use fo 


buffer 


mber 
r test 
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’ 


; Start of code 


PER RREALERAR ERA ER ER ERER ER RE ER ERE EER ER ERE RERERERER ER EER ERR EERE RERRRERERERE 


-PSECT CODE, EXE, NOWRT, PAGE 
-ENTRY START, “M<> 


; Assign a port to the LAN device. 


SASSIGN_S DEVNAM=LANDSC, CHAN=DEVCHAN 


BLBS RO,10$ ; Branch if succeeded 
MOVAL DMSG, R9 ; Get address of error message 
BRW EXIT ; Print message and exit 


; Set up the port's characteristics. 


10S: MOVAL EMSG, R9 ; Assume error message address 


SQIOW_S FUNC=#<IO$_SETMODE! IOSM_CTRL! IOSM_STARTUP> 
CHAN=DEVCHAN, IOSB=IOSB, - 
P2=#SETPARMDSC 


BLBC RO,208 ; Branch if failed 
MOVZWL IOSB, RO ; Get status from 
BLBS RO, 30$ ; Branch if succee 
208: BRW EXIT ; Print message an 


; Issue the SENSEMODE QIO to get our physical address for the loopback 


y, message. 


30$: SQIOW_S FUNC=#<IO$_SENSEMODE ! LO$M_CTRL>, - 
CHAN=DEVCHAN, IOSB=IOSB, - 
P2=#SENSEDSC 


BLBC RO, 20$ ; Branch if failed 
MOVZWL IOSB, RO ; Get status from 
BLBC RO, 20$ ; Branch if failed 


; Locate the PHA parameter in the SENSEMODE buffer and copy it into the 
; LOOPBACK transmit message. The PHA parameter is a string parameter. 


fi 


IOSB 
ded 
d exit 


IOSB 


409 


Local Area Network (LAN) Device Drivers 
Application Programming Notes 


MOVAB SENSEBUF, RO 


40s: BBS #*XC, (RO) ,50$ 
ADDL #6,RO 
BRB 40S 

508: BICW3 #°XF000, (RO)+,R1 
CMPW R1, #NMASC_PCLI_PHA 
BEQL 60$ 
ADDW (RO) +,R0 
BRW 40S 

.IF NOT_DEFINED VAX 


-DISABLE FLAGGING 
- ENDC 
60S: MOVL 2 (RO), FORW 
MOVW 6 (RO) , FORW+4 
-IF NOT_DEFINED VAX 
- ENABLE FLAGGING 
- ENDC 


; Transmit the loopback message. 


Start at beginning of buffer 
Branch if a string parameter 
Skip over longword parameter 
Check next parameter 

Get type field less flag bits 
Is this the PHA parameter? 
Branch if so 

Skip over string parameter 
Check next parameter 


Copy our address to the loopback 
packet we are about to transmit 


SQIOW_S FUNC=#1I0S_WRITEVBLK, CHAN=DEVCHAN, IOSB=IOSB, — 
P1=XMTBUF, P2=#XMTBUFLEN, P5=#XMTP5 


BLBC RO, 70$ 

MOVZWL IOSB, RO 

BLBS RO, 80$ 
708: BRW EXIT 


’ 
’ 
’ 


’ 


Branch if failed 

Get status from IOSB 
Branch if succeeded 
Print message and exit 


; Look for a response. We use the NOW function modifier on the READ so that 


; we don't hang here waiting forever if there is no response. If there is no 


; response in 1000 receive attempts, 


we declare no response status. 


80S: MOVL #1000,R2 ; Check 1000 times 
90S: SQIOW_S FUNC=#I0$_READVBLK! IO$M_NOW, CHAN=DEVCHAN, IOSB=IOSB, — 
P1=RCVBUF, P2=#RCVBUFLEN, P5=#RCVP5 
BLBC RO, EXIT ; Branch if failed 
MOVZWL IOSB, RO ; Get status from IOSB 
BLBS RO,100$ ; Branch if succeeded 
CMPL RO, #SS$_ENDOFFILE ; Was there just no message available? 
BNEQ EXIT ; Branch if failed 


SOBGTR R2,90$ 


; No response in 1000 attempts. 


MOVAL LMSG, RO 
BRW EXIT 


; Received a message. 


1008: MOVAL GMSG, RY 


’ 


’ 


Try again 


Get address of lost message 
Print message and exit 


Get address of success message 


; The test is done. Call LIBSPUT_OUTPUT to display the test status. 


EXIT: PUSHL R9 
CALLS #1,G*LIBSPUT_OUTPUT 
SEXIT_S 
- END START 
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Pl = Address of message to print 
Print the message 
Exit 
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Example 9-3 LAN802.C Local Area Network Programming Example 


[ROKR KK KKK KK IKK IKK I KK IKK IK IKK IKK IK IR IO IR IK OK 


* LAN Sample Test Program 


This LAN test program sends a MOP loopback message to the Loopback Assistant 
Multicast address and waits for a response. The program uses the LAN device 
EWAO. To use a different device, change the device name in the program or 
define the desired lan device as EWAO. 


To build on VAX: 
$ CC LAN802E 
$ LINK LAN802E,SYSSINPUT:/OPT 
SYSSSHARE:VAXCRTL.EXE/SHARE 


Note: NMADEF.H must be supplied containing definitions for: 


#define NMASC_PCLI_FMT 2770 
#define NMASC_PCLI_PID 2774 
#define NMASC_PCLI_PHA 2820 
#define NMASC_LINFM_802E 0 


To build on Alpha, 164: 
$ CC LAN802E+SYSSLIBRARY:SYSSLIB_C.TLB/LIB 
$ LINK LAN802E 


To run: 
$ RUN LAN802E 


TA AA AAA I IA IA A IRI RRR IR AIA IA IA IA IA IA IA A I I / 


include <ctype> /* Character type classification macros/routines */ 
include <descrip> /* For VMS descriptor manipulation */ 

include <iodef> /* I/O function code definitions */ 

include "nmadef.h" /* LAN parameter definitions */ 

include <ssdef> /* System service return status code definitions */ 
include <starlet> /* System library routine prototypes */ 

include <stdio> /* ANSI C Standard Input/Output */ 

include <stdlib> /* General utilities */ 

include <string> /* String handling */ 

include <stsdef> /* VMS status code definitions */ 

define $SUCCESS (status) (((status) & STSSM_SUCCESS) == SS$_NORMAL) 

define $FAIL(status) (((status) & STSSM_SUCCESS) != SS$_NORMAL) 

pragma nomember_alignment 

struct parm_802e 


short pcli_fmt;/* Format - 802E */ 
int fmt_value; 
short peli_pid; /* Protocol ID - 08-00-2B-90-00 */ 
short pid_length; 
char pid_value[5]; 
} setparm_802e = {NMASC_PCLI_FMT, NMASC_LINFM_802E, 
NMASC_PCLI_PID, 5, 8,0,0x2B,0x90,0}; 


struct setparmdsc 
{ 

int parm_len; 

void *parm_buffer; 
hi 


struct setparmdsc setparmdsc_loop = { 
sizeof (setparm_802e),&setparm_802e}; 
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struct p5_param /* P5 Receive header buffer */ 
{ 

unsigned char da[6]; 

unsigned char sa[6]; 

char misc[20]; 
hi 


struct iosb /* IOSB structure */ 
{ 
short w_err; /* Completion status */ 
short w_xfer_size; /* Transfer size */ 
short w_addl; /* Additional status */ 
short w_misc; /* Miscellaneous */ 
hi 
struct. ascid /* Device descriptor for assign */ 


{ 
short w_len; 
short w_info; 
char *a_string; 


} devdsc = {4,0,"EWA0"}; 
struct iosb qio_iosb; /* IOSB structure */ 
struct p5_param rcv_param; /* Receive header structure */ 
struct p5_param xmt_param = { /* Transmit header structure */ 
Oxcr, 0,0; 0; 0,0}7 
char rcev_buffer[512]; /* Receive buffer */ 
char xmt_buffer[20] = { /* Transmit buffer */ 
0,0, /* Skip count */ 
2,0; /* Forward request */ 
0,/:07:0.,:07:0.,.0; /* Forward address */ 
105 /* Reply request */ 
0,0}; 
char sense_buffer[512]; /* Sensemode buffer */ 
struct setparmdsc sensedsc_loop = {sizeof (sense_buffer),sense_buffer}; 
/* 
* MAIN 
*7/ 


main(int argc, char *argv[]) 

{ 
int. 2, 4} /* Scratch */ 
int chan; /* Channel assigned */ 
int status; /* Return status */ 


/* 
* Start a channel. 


*/ 


status = sysSassign(&devdsc, &chan,0,0); 
if (SFAIL(status)) exit (status); 
status = 
sys$qiow (0, chan, IO$_SETMODE | IO$M_CTRL| IOSM_STARTUP, &qio_iosb,0,0,0,&setparmdsc_loop,0,0,0,0); 
if (SSUCCESS(status)) status = qio_iosb.w_err; 
if (SFAIL(status)) { 
printf("IOSB addl status = %04X %04X\n",qio_iosb.w_addl,qio_iosb.w_misc) ; 
exit (status) ; 
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* Issue the SENSEMODE QIO to get our physical address for the loopback message. 


ay: 


status = sys$qiow(0, chan, IO$_SENSEMODE | IO$M_CTRL, &qio_iosb,0,0,0,&sensedsc_loop,0,0,0,0); 


if (SSUCCESS(status)) status = qio_iosb.w_err; 
if (SFAIL(status)) { 


printf("IOSB addl status = %04X %04X\n",qio_iosb.w_addl, qio_iosb.w_misc) ; 


exit (status); 


/* 
* Locate the PHA parameter in the SENSEMODE buffer and copy it into the 
* LOOPBACK transmit message. The PHA parameter is a string parameter. 
wf 

3 = 0; 

while (j < sizeof(sense_buffer)) { 

i = (sense_buffer[j] + (sense_buffer[j+1] << 8)); 
if (0x1000 & i) { 
if ((i & OxFFF) == NMASC_PCLI_PHA) { 
memcpy (&xmt_buffer[4],&sense_buffer[j+4],6); 
break; 
} 
j += (sense_buffer[j+2] + (sense_buffer[j+3] << 8)) + 4; 
} else 
j += 6; /* Skip over longword parameter */ 
} 
/* 
* Transmit the loopback message. 
*/ 


status = sys$qiow(0,chan, IO$_WRITEVBLK, &qio_iosb,0,0,&xmt_buffer[0], 
sizeof (xmt_buffer),0,0,&xmt_param, 0); 
if (SSUCCESS(status)) status = qio_iosb.w_err; 
if (SFAIL(status)) { 
printf("IOSB addl status = %04X %04X (on transmit) \n", 
qio_iosb.w_addl,qio_iosb.w_misc) ; 
exit (status); 


/* 
* Look for a response. We use the NOW function modifier on the READ so 
* we don't hang here waiting forever if there is no response. If there 


* response in 1000 receive attempts, we declare no response status. 


*/ 


for (i=0;i<1000;it+) { 


status = sys$qio(0,chan, I0$_READVBLK | IO$M_NOW, &qio_iosb,0,0,&rcv_buffer[0], 


sizeof (rcv_buffer),0,0,rcv_param, 0) ; 
if (SSUCCESS(status)) status = qio_iosb.w_err; 
if ($SUCCESS(status)) break; 
} 
if (SSUCCESS (status) ) 
printf("Successful test\n"); 
else 
printf("No response\n"); 


that 
is no 
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10 Optional Features for Improving I/O 
Performance 


Two features of OpenVMS Alpha and 164 provide dramatically improved I/O performance: Fast I/O and Fast 
Path. These features are designed to promote OpenVMS as a leading platform for database systems. 
Performance improvement results from reducing the CPU cost per I/O request and improving symmetric 
multiprocessing (SMP) scaling of I/O operations. The CPU cost per I/O is reduced by optimizing code for 
high-volume I/O and by using better SMP CPU memory cache. SMP scaling of I/O is increased by reducing 
the number of spinlocks taken per I/O and by substituting finer-granularity spinlocks for global spinlocks. 


The improvements follow a natural division that already exists between the device-independent and 
device-dependent layers in the OpenVMS I/O subsystem. The device-independent overhead is addressed by 
Fast I/O, which is a set of lean system services that can substitute for certain $QIO operations. Using these 
services requires some coding changes in existing applications, but the changes are usually modest and well 
contained. The device-dependent overhead is addressed by Fast Path, which is an optional performance 
feature that creates a “fast path” to the device. It requires no application changes. 


Fast I/O and Fast Path can be used independently; however, together they can provide a 45 percent reduction 
in CPU cost per I/O on uniprocessor systems and a 52 percent reduction on multiprocessor systems. 


10.1 Fast /O 


Fast I/O is a set of three system services that were developed as a $QIO alternative built for speed. These 
services are not a $QIO replacement; $QIO is unchanged, and $QIO interoperation with these services is fully 
supported. Rather, the services substitute for a subset of $QIO operations, namely, only the high-volume 
read/write I/O requests. 


The Fast I/O services support 64-bit addresses for data transfers to and from disk and tape devices. 


While Fast I/O services are available on OpenVMS VAX, the performance advantage applies only to 
OpenVMS Alpha and I64. OpenVMS VAX has a run-time library (RTL) compatibility package that translates 
the Fast I/O service requests to $QIO system service requests, so one set of source code can be used on VAX, 
Alpha, and 164 systems. 


10.1.1 Fast /O Benefits 


The performance benefits of Fast I/O result from streamlining high-volume I/O requests. The Fast I/O system 
service interfaces are optimized to avoid the overhead of general-purpose services. For example, I/O request 
packets (IRPs) are now permanently allocated and used repeatedly for I/O rather than allocated and 
deallocated anew for each I/O. 


The greatest benefits stem from having user data buffers and user I/O status structures permanently locked 
down and mapped using system space. This allows Fast I/O to do the following: 


e For direct I/O, avoid per-I/O buffer lockdown or unlocking. 


e For buffered I/O, avoid allocation and deallocation of a separate system buffer, because the user buffer is 
always addressable. 
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e Complete Fast I/O operations at IPL 8, thereby avoiding the interrupt chaining usually required by the 
more general-purpose $QIO system service. For each I/O, this eliminates the IPL 4 IOPOST interrupt and 
a kernel AST. 


In total, Fast I/O services eliminate four spinlock acquisitions per I/O (two for the MMG spinlock and two for 
the SCHED spinlock). The reduction in CPU cost per I/O is 20 percent for uniprocessor systems and 10 
percent for multiprocessor systems. 


10.1.2 Using Buffer Objects 


The lockdown of user-process data structures is accomplished by buffer objects. A “buffer object” is process 
memory whose physical pages have been locked in memory and double-mapped into system space. After 
creating a buffer object, the process remains fully pageable and swappable and the process retains normal 
virtual memory access to its pages in the buffer object. 


If the buffer object contains process data structures to be passed to an OpenVMS system service, the 
OpenVMS system can use the buffer object to avoid any probing, lockdown, and unlocking overhead 
associated with these process data structures. Additionally, double-mapping into system space allows the 
OpenVMS system direct access to the process memory from system context. 


To date, only the $QIO system service and the Fast I/O services have been changed to accept buffer objects. 
For example, a buffer object allows a programmer to eliminate I/O memory management overhead. On each 
I/O, each page of a user data buffer is probed and then locked down on IJ/O initiation and unlocked on I/O 
completion. Instead of incurring this overhead for each I/O, it can be done once at buffer object creation time. 
Subsequent I/O operations involving the buffer object can completely avoid this memory management 
overhead. 


Two system services can be used to create and delete buffer objects, respectively, and can be called from any 
access mode. To create a buffer object, the $CREATE_BUFOBJ system service is called. This service expects 
as inputs an existing process memory range and returns a buffer handle for the buffer object. The buffer 
handle is an opaque identifier used to identify the buffer object on future I/O requests. The 
$DELETE_BUFOBJ system service is used to delete the buffer object and accepts as input the buffer handle. 
Although image rundown deletes all existing buffer objects, it is good form for the application to clean up 
properly. 


A 64-bit equivalent version of the $CREATE_BUFOBJ system service ($CREATE_BUFOBJ_64) can be used 
to create buffer objects from the new 64-bit P2 or S2 regions. The $DELETE_BUFOBJ system service can be 
used to delete 32-bit or 64-bit buffer objects. 


Buffer objects require system management. Because buffer objects tie up physical memory, extensive use of 
buffer objects requires system management planning. All the bytes of memory in the buffer object are 
deducted from a systemwide system parameter called MAXBOBMEM (maximum buffer object memory). 
System managers must set this parameter correctly for the application loads that run on their systems. 


The MAXBOBMEM parameter defaults to 100 Alpha pages, but for applications with large buffer pools it will 
likely be set much larger. To prevent user-mode code from tying up excessive physical memory, user-mode 
callers of $CREATE_BUFOBJ must have a new system identifier, VMS$BUFFER_OBJECT_USER, 
assigned. This new identifier is automatically created in an OpenVMS Version 7.0 upgrade if the file 
SYS$SYSTEM:RIGHTSLIST.DAT is present. The system manager can assign this identifier with the DCL 
command SET ACL command to a protected subsystem or application that creates buffer objects from user 
mode. It may also be appropriate to grant the identifier to a particular user with the Authorize utility 
command GRANT/IDENTIFIER (for example, to a programmer who is working on a development system). 


There is currently a restriction on the type of process memory that can be used for buffer objects. Global 
section memory cannot be made into a buffer object. 
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10.1.3 Differences Between Fast I/O Services and $QIO 


The precise definition of high-volume I/O operations optimized by Fast I/O services is important. I/O that does 
not comply with this definition either is not possible with the Fast I/O services or is not optimized. The 
characteristics of the high-volume I/O optimized by Fast I/O services can be seen by contrasting the operation 
of Fast I/O system services to the $QIO system service as follows: 


The $QIO system service I/O status block (IOSB) is replaced by an I/O status area (IOSA) that is larger 
and quadword aligned. The transfer byte count returned in IOSA is 64 bits, and the field is aligned on a 
quadword boundary. Unlike the IOSB, which is optional, the IOSA is required. 


User data buffers must be aligned to a 512-byte boundary. 


All user process structures passed to the Fast I/O system services must reside in buffer objects. This 
includes the user data buffer and the IOSA. 


Only transfers that are multiples of 512 bytes are supported. 


Only the following function codes are supported: IO$_READVBLK, IO$_READLBLK, I0$_WRITEVBLK, 
and IO$_WRITELBLK. 


Only I/O to disk and tape devices is optimized for performance. 


No event flags are used with Fast I/O services. If application code must use an event flag in relation to a 
specific I/O, then the Event No Flag EFN (EFN$C_ENF) can be used. This event flag is a no-overhead 
EFN that can be used in situations when an EFN is required by a system service interface but has no 
meaning to an application. 


For example, Fast I/O services do not use EFNs, so the application cannot specify a valid EFN associated 
with the I/O to the $SYNCH system service with which to synchronize I/O completion. To resolve this 
issue, the application can call the $SYNCH system service passing as arguments: EFN$C_ENF and the 
address of the appropriate IOSA. Specifying EFN$C_ENF signifies to $SYNCH that no EFN is involved 
in the synchronization of the I/O. Once the IOSA has been written with a status and byte count, return 
from the $SYNCH call occurs. The IOSA is now the central point of synchronization for a given Fast I/O 
(and is the only way to determine whether the asynchronous I/O is complete). 


To minimize arguments passing overhead to these services, the $QIO parameters P3 through P6 are 
replaced by a single argument that is passed directly by the Fast I/O system services to device drivers. For 
disk-like devices, this argument is the media address (VBN or LBN) of the transfer. For drivers with 
complex parameters, this argument is the address of a descriptor or of a buffer specific to the device and 
function. 


Segmented transfers are supported by Fast I/O but are not fully optimized. There are two major causes of 
segmented transfers. The first is disk fragmenting. While this can be an issue, it is assumed that sites 
seeking maximum performance have eliminated the overhead of segmenting I/O due to fragmentation. 


A second cause of segmenting is issuing an I/O that exceeds the port's maximum limit for a single 
transfer. Transfers beyond the port maximum limit are segmented into several smaller transfers. Some 
ports limit transfers to 64KB. If the application limits its transfers to less than 64KB, this type of 
segmentation should not be a concern. 


10.1.4 Using Fast I/O Services 


The three Fast I/O system services are: 


$10_SETUP—-Sets up an I/O 
$10_PERFORM[W]—-Performs an I/O request 
$10_CLEANUP—Cleans up an I/O request 
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10.1.4.1 Using Fandles 


A key concept behind the operation of the Fast I/O services is the file handle or fandle. A fandle is an opaque 
token that represents a “setup” I/O. A fandle is needed for each I/O outstanding from a process. 


All possible setup, probing, and validation of arguments is performed off the mainline code path during 
application startup with calls to the $IO_SETUP system service. The I/O function, the AST address, the 
buffer object for the data buffer, and the IOSA buffer object are specified on input to $1O_SETUP service, and 
a fandle representing this setup is returned to the application. 


To perform an I/O, the $1O_PERFORM system service is called, specifying the fandle, the channel, the data 
buffer address, the IOSA address, the length of the transfer, and the media address (VBN or LBN) of the 
transfer. 


If the asynchronous version of this system service, $10_PERFORM, is used to issue the I/O, then the 
application can wait for I/O completion using a $SYNCH specifying EFN$C_ENF and the appropriate IOSA. 
The synchronous form of the system service, $IO_PERFORMW, is used to issue an I/O and wait for it to 
complete. Optimum performance comes when the application uses AST completion; that is, the application 
does not issue an explicit wait for I/O completion. 


To clean up a fandle, the fandle can be passed to the $1O_CLEANUP system service. 


10.1.4.2 Modifying Existing Applications 
Modifying an application to use the Fast I/O services requires a few source-code changes. For example: 


1. A programmer adds code to create buffer objects for the IOSAs and data buffers. 


2. The programmer changes the application to use the Fast I/O services. Not all $QIOs need to be converted. 
Only high-volume read/write I/O requests should be changed. 


A simple example is a “database writer” program, which writes modified pages back to the database. 
Suppose the writer can handle up to 16 simultaneous writes. At application startup, the programmer 
would add code to create 16 fandles by 16 $I1O_SETUP system service calls. 


3. In the main processing loop within the database writer program, the programmer replaces the $QIO calls 
with $10 PERFORM calls. Each $10_PERFORM call uses one of the 16 available fandles. While the I/O 
is in progress, the selected fandle is unavailable for use with other I/O requests. The database writer is 
probably using AST completion and recycling fandle, data buffer, and IOSA once the completion AST 
arrives. 


If the database writer routine cannot return until all dirty buffers are written (that is, it must wait for all 
I/O completions), then $10_PERFORMW can be used. Alternatively $10_PERFORM calls can be followed 
by $SYNCH system service calls passing the EFN$C_ENF argument to await I/O completions. 


The database writer will run faster and scale better because I/O requests now use less CPU time. 


4, When the application exits, an $I0_CLEANUP system service call is done for each fandle returned by a 
prior $I0O_SETUP system service call. Then the buffer objects are deleted. Image rundown performs 
fandle and buffer object cleanup on behalf of the application, but it is good form for the application to 
clean up properly. 


10.1.4.3 I/O Status Area (IOSA) 


The central point of synchronization for a given Fast I/O is its IOSA. The IOSA replaces the $QIO system 
service's IOSB argument. Larger than the IOSB argument, the byte count field in the IOSA is 64 bits and 
quadword aligned. Unlike the $QIO system service, Fast I/O services require the caller to supply an IOSA and 
require the IOSA to be part of a buffer object. 
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The IOSA context field can be used in place of the $QIO system service ASTPRM argument. The $QIO 
ASTPRM argument is typically used to pass a pointer back to the application on the completion AST to locate 
the user context needed for resuming a stalled user-thread; however, for the $I0O_PERFORM system service, 
the ASTPRM on the completion AST is always the IOSA. Because there is no user-settable ASTPRM, an 
application can store a pointer to the user-thread context for this I/O in the IOSA context field and retrieve 
the pointer from the IOSA in the completion AST. ) 


10.1.4.4 $10 SETUP 


The $I0_SETUP system service performs the setup of an I/O and returns a unique identifier for this setup 
I/O, called a fandle, to be used on future I/Os. The $1O_SETUP arguments used to create a given fandle 
remain fixed throughout the life of the fandle. This has implications for the number of fandles needed in an 
application. For example, a single fandle can be used only for reads or only for writes. If an application module 
has up to 16 simultaneous reads or writes pending, then potentially 32 fandles are needed to avoid any 
$1O0_SETUP calls during mainline processing. 


The $I0O_SETUP system service supports an expedite flag, which is available to boost the priority of an I/O 
among the other I/O requests that have been handed off to the controller. Unrestrained use of this argument 
is useless, because if all I/O is expedited, nothing is expedited. Note that this flag requires the use of ALTPRI 
and PHY_IO privilege. 


10.1.4.5 $10_PERFORM[W] 


The $10_PERFORM[W] system service accepts a fandle and five other variable I/O parameters for the 
high-performance I/O operation. The fandle remains in use to the application until the $I10O_PERFORMW 
returns or if $I10_PERFORM is used until a completion AST arrives. 


The CHAN argument to the fandle contains the data channel returned to the application by a previous file 
operation. This argument allows the application the flexibility of using the same fandle for different open files 
on successive I/Os; however, if the fandle is used repeatedly for the same file or channel, then an internal 
optimization with $10_PERFORM is taken. 


Note that $10_PERFORM was designed to have no more than six arguments to take advantage of the HP 
OpenVMS Calling Standard, which specifies that calls with up to six arguments can be passed entirely in 
registers. 


10.1.4.6 $I10_CLEANUP 
A fandle can be cleaned up by passing the fandle to the $I1O_CLEANUP system service. 


10.1.4.7 Fast /O FDT Routine (ACP_STD$FASTIO_BLOCK) 


Because $10O_PERFORM supports only four function codes, this system service does not use the generalized 
function decision table (FDT) dispatching that is contained in the $QIO system service. Instead, 
$10_PERFORM uses a single vector in the driver dispatch table called DDT$PS_FAST_FDT for the four 
supported functions. The DDT$PS_FAST_FDT field is a FDT routine vector that indicates whether the device 
driver called by $I0_PERFORM is set up to handle Fast I/O operations. A nonzero value for this field 
indicates that the device driver supports Fast I/O operations and that the I/O can be fully optimized. 


If the DDT$PS_FAST_FDT field is zero, then the driver is not set up to handle Fast I/O operations. The 
$10_PERFORM system service tolerates such device drivers, but the I/O is only slightly optimized in this 
circumstance. 


The OpenVMS disk and tape drivers that ship as part of OpenVMS Version 7.0 have added the following line 
to their driver dispatch table (DDTAB) macro: 


FAST_FDT=ACP_STDSFASTIO_BLOCK,- ; Fast-IO FDT routine 
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This line initializes the DDT$PS_FAST_FDT field to the address of the standard Fast I/O FDT routine, 
ACP_STD$FASTIO_ BLOCK. 


If you have a disk or tape device driver that can handle Fast I/O operations, you can add this DDTAB macro 
line to your driver. If you cannot use the standard Fast I/O FDT routine, ACP_STD$FASTIO_BLOCK, you 
can develop your own based on the model presented in this routine. 


10.1.5 Additional Information 


Refer to the HP OpenVMS System Services Reference Manualfor additional information about the following 
Fast I/O system services: 


e $CREATE_BUFOBJ 

e $DELETE_BUFOBJ 

e $CREATE_BUFOBJ_64 
e $I10_SETUP 

e $I10_PERFORM 

e $I10_CLEANUP 


To see a sample program that demonstrates the use of buffer objects and the Fast I/O system services, refer to 
the IO_PERFORM.C program in the SYS$EXAMPLES directory. 


10.2 Fast Path (Alpha and 164 Only) 


Fast Path is an optional feature designed to improve I/O performance. There are three factors which serve to 
throttle performance for OpenVMS on SMP systems. 


1. Time spent by a CPU waiting for memory to be faulted into its cache. 

2. Contention for the SCS/IOLOCKS8 spinlock. 

3. Contention for the primary CPU on which all I/O completion is processed. 
Fast Path addresses these factors as follows: 


1. Select a secondary CPU for a given device or port. and cause all I/O for that device to originate and 
complete on that CPU. This offloads the primary CPU and reduces cache faults. 


2. Replace dependence upon SCS/IOLOCKS8 spinlock by providing a port-specific spinlock whenever 
possible. 


3. For the most common I/O requests, preallocate resources and provide an optimized path through the 
mainline code. 


Using Fast Path features does not require source-code changes. It does require major changes to device 
drivers, so it has been implemented only for the newer high-performance devices. These currently service 
many CI, Fibre Channel, parallel SCSI, and LAN devices. 
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Table 10-1 lists the supported ports for each OpenVMS Alpha version. 


Table 10-1 Supported Ports for Each Version of OpenVMS Alpha and I64 
Version Supported Ports 
7.3-2 SMART Array 53xx, many LAN devices 
7.3-1 KZPEA 
7.3 CIXCD, CIPCA, KGPSA, KZPBA 
all CIXCD, CIPCA 
7.0 CIXCD 


Prior to OpenVMS Alpha Version 7.3-1, all hardware interrupts took place on the primary CPU. Interrupts 
from Fast Path enabled devices would have to be redirected from the primary CPU to a "preferred" CPU. 
However, this redirection still involved the primary CPU, and also incurred interprocessor overhead. 


Starting with OpenVMS Alpha Version 7.3-1, hardware interrupts that are targetted for a "preferred" CPU go 
directly to the "preferred" CPU, thereby eliminating any I/O processing in the primary CPU. This major Fast 
Path enhancement is known as distributed interrupts. 


NOTE This feature is available on Fibre Channel, CI, and some SCSI ports on AlphaServer DS20, 
ES40/45, and GS series systems. 


For more information about Fibre Channel, SCSI, and CI configurations, refer to Guidelines for OpenVMS 
Cluster Configurations. 


10.2.1 Using Fast Path Features 


Preferred CPU Selection 


All Fast Path ports are assignable to CPUs. You can set a system parameter specifying the set of CPUs that 
are allowed to serve as preferred CPUs. This set is called the set of allowable CPUs. At any point in time, 
the set of CPUs that currently can have ports assigned to them, called the set of usable CPUs, is the 
intersection of the set of allowable CPUs, and the current set of running CPUs. 


Each Fast Path Port is initially assigned to a CPU by the FASTPATH_SERVER process that runs at port 
initialization time. This process executes an automatic assignment algorithm that spreads Fast Path ports 
evenly among the usable CPUs. The FASTPATH_SERVER process also runs whenever a secondary CPU is 
started, and whenever the set of system parameters specifying the allowable CPUs is changed. 


If the primary CPU is in the set of allowable CPUs, the initial distribution will be biased against the primary 
CPU in that a port will only be assigned to the primary after ports have been assigned to each of the other 
usable CPUs. 


To identify a device or port's current preferred CPU, you can use either $GETDVI or the SHOW 
DEVICE/FULL command. To identify the Fast Path ports currently assigned to a CPU, you use the SHOW 
CPU /FULL command. 


You can directly assign a Fast Path port to a CPU, or request the system to automatically select the port's 
preferred CPU from a specific set of CPUs. To do this, you either issue a $QIO or use the SET 
DEVICE/PREFERRED_CPU command. This will also set the port's User Preferred CPU to be the selected 
CPU. 
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You can clear the port's User Preferred CPU by issuing either a $QIO, or by using the SET 
DEVICE/NOPREFERRED CPU DCL command. 


You can redistribute the system assignable Fast Path ports across a subset of the set of usable CPUs by 
calling the $1O_FASTPATH system service. 


Optimizing Application Performance 


Processes running on a port's preferred CPU have an inherent advantage when issuing I/O to a port in that 
the overhead to assign the I/O to the preferred CPU can be avoided. An application process can use the 
$PROCESS_AFFINITY system service to assign itself to the preferred CPU of the device to which the 
majority of its I/O is sent. 


With proper attention to assignment, a process's execution need never leave the preferred CPU. This presents 
a scalable process and I/O scheme for maximizing multiprocessor system operation. Like most RISC systems, 
Alpha system performance is highly dependent on the performance of CPU memory caches. Process 
assignment and preferred CPU assignment are two keys to minimizing the memory stalls in the application 
and in the operating system, thereby maximizing multiprocessor system throughput. 


10.2.2 Managing Fast Path 


This section describes how to manage Fast Path. 


10.2.2.1 Fast Path System Parameters 
There are three FAST_PATH system parameters: 
e FAST_PATH 

e FAST _PATH_PORTS 

e IO_PREFER_CPUS 


These parameters can be used to control Fast Path as follows: 


FAST_PATH FAST_PATH is a static system parameter that enables (1) or disables (0) 
the Fast Path performance features for all Fast Path-capable ports. 


Fast Path is enabled by default. 


FAST_PATH_PORTS FAST_PATH_PORTS is a 32-bit mask. Once Fast Path has been enabled 
by setting FAST_PATH to 1, FAST_PATH_PORTS can be used to 
selectively disable Fast Path for some specific adapter types. 
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The value of the FAST_PATH_PORTS system parameter is the sum of the 
values of the bits that have been set. Table 10-2 describes thebit mask: 


Table 10-2 FAST_PATH_PORTS Bit Masks 

Bit Mask Description 

0 00000001 0 = Fast Path is ENABLED for KZPBA ports when FAST_PATH is set to 1. 
1 = Fast Path is DISABLED for KZPBA ports. 

1 00000002 0 = Fast Path is ENABLED for KGPSA ports when FAST_PATH is set to 1. 
1 = Fast Path is DISABLED for KGPSA ports. 

2 00000004 0 = Fast Path is ENABLED for KZPEA ports when FAST_PATH is set to 1. 
1 = Fast Path is DISABLED for KZPEA ports. 

3 00000008 0 = Fast Path is ENABLED for LAN ports when FAST_PATH is set to 1. 
1 = Fast Path is DISABLED for LAN ports. 

4 00000010 0 = Fast Path is ENABLED for KZPDC ports when FAST_PATH is set to 1. 


1 = Fast Path is DISABLED for KZPDC ports. 


IO_PREFER_CPUS 


The remaining bits are reserved for possible future adapter types. 


The default setting for FAST_PATH_PORTS is 0; therefore, all supported 


ports are enabled. 


Note that CI drivers are not controlled by FAST_PATH_PORTS. Fast Path 


for CI is enabled and disabled exclusively by the FAST_PATH system 


parameter. 


IO_PREFER_CPUS is a dynamic system parameter that controls the set 


of CPUs available for use as Fast Path preferred CPUs. 


IO_PREFER_CPUS is a CPU bit mask specifying the CPUs that are 


allowed to serve as preferred CPUs and thus can be assigned a Fast Path 


port. CPUs whose bit is set in the IO_PREFER_CPUS bit mask are 


enabled for Fast Path port assignment. IO_PREFER_CPUS defaults to -1, 
which specifies that all CPUs are allowed to be assigned Fast Path ports. 


You may want to disable the primary CPU from serving as a preferred 
CPU by clearing its bit in IO_LPREFER_CPUS. This will reserve the 


primary for use by non-Fast Path IO operations. 


Changing the value of IO_PREFER_CPUS causes the 


FASTPATH_SERVER process to execute the automatic assignment 
algorithm that spreads Fast Path ports evenly among the new set of 


usable CPUs. 


10.2.2.2 Identifying and Setting a Port's Preferred CPU 


Following are the commands used to identify and set a preferred CPU for a port. 
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DCL SHOW DEVICE/FULL or $GETDVI DVI$_PREFERRED_CPU 


DCL SHOW CPU /FULL 


To identify the preferred CPU for any Fast Path-capable device when Fast 
Path is enabled, use the DCL command SHOW DEVICE/FULL to display 
— whether or not the device supports Fast Path — the current preferred 
CPU ID and, if set, the User Preferred CPU ID for a port or disk device. 


Alternatively, the $GETDVI system service or the DCL F$GETDVI lexical 
function will return the preferred CPU for a given device or file. The 
$GETDVI system service item code is DVI$_PREFERRED_CPU, and the 
F$GETDVI item code string argument is PREFERRED_CPU. The return 
argument is a 32-bit CPU bit mask with a bit set indicating the preferred 
CPU. A return argument containing a bit mask of zero indicates that no 
preferred CPU exists, either because Fast Path is disabled or the device is 
not a Fast Path-capable device. The return argument serves as a CPU bit 
mask input argument to the $PROCESS_AFFINITY system service. The 
argument can be used to assign an application process to the optimal 
preferred CPU. 


For an application seeking optimal Fast Path benefits, you can code each 
application process to identify and run on the preferred CPU where the 
majority of the process' I/O activity occurs. 


A high-availability feature of OpenVMS Cluster Systems is that 
dual-pathed devices automatically fail over to a secondary path, if the 
primary path becomes inoperable. Because a Fast Path device could fail 
over to another path or port, and thereby, to another preferred CPU, an 
application should occasionally reissue the $GETDVI in a timer thread to 
check that process assignment is optimal. 


You can use this DCL command to identify whether a CPU is enabled for 
use as a preferred CPU, and the current set of ports assigned to that CPU. 


DCL SET /PREFERRED_CPU and /NOPREFERRED_CPU 


These commands allow you to specify a CPU or a set of candidate CPUs 
from which the operating system will choose the CPU to assign to the Fast 
Path port. The chosen CPU is called the preferred CPU for this Fast Path 
port. The Fast Path port's interrupt I/O completion processing and I/O 
initiation processing will be performed on this preferred CPU. 


In addition to selecting the preferred CPU, the User Preferred CPU will be 
set for this port. Setting the User Preferred CPU prevents the port from 
being reassigned to another CPU unless the User Preferred CPU is being 
stopped. The qualifier can be negated. When the /NOPREFERRED_CPUS 
qualifier is specified, the User Preferred CPU will be cleared for the port, 
but it still remains a Fast Path port, and the current preferred CPU will 
not be changed. 


If both /PREFERRED_CPUS and /NOPREFERRED_CPUS are specified 
on the same command line, /NOPREFERRED_CPUS is ignored. 


$QIO I0$_SETPRFPATH ! IO$M_PREFERRED_CPU [!IO$M_SYS_ASSIGNABLE] 
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You can change the assignment of a Fast Path port to a CPU by issuing a 
$QIO I0$_SETPRFPATH (Set Preferred Path) to the port device, for 
example, PNAO. The IO$M_PREFERRED_CPU modifier must be set, and 
the $QIO argument P1 must be set to either 0 or the address of a 32-bit 
CPU bit mask with a bit set indicating the new preferred CPU. On return 
from the I/O, the port and its associated devices are all assigned to a new 
preferred CPU. Note that explicitly setting the preferred CPU overrides 
any default assignment of Fast Path ports to CPUs. This interface allows 
you the flexibility to load balance I/O activity over multiple CPUs in an 
SMP system. This is important because I/O activity can change over the 
course of a day or week. 


The $QIO passes in either a set containing one or more candidate CPUs, 
or 0 as a wildcard value indicating the set of usable CPUs. If the candidate 
set contains only one CPU, you are explicitly designating the new 
preferred CPU. If the candidate set contains multiple CPUs, you are 
requesting use of the automatic preferred CPU assignment algorithm to 
select a suitable CPU from the candidate set. 


Including the IO$M_SYS_ASSIGNABLE modifier inhibits setting the 
selected CPU as the device's User Preferred CPU. 


The $QIO or the SET DEVICE/PREFERRED_CPU command will make a 
best effort to assign the port to a CPU. However, it is possible for this 
request to return failure for the following reasons: 


e There is no intersection between the candidate set and the node's set 
of usable CPUs. 


e There is resource contention. If after a reasonable effort the request is 
unable to acquire a key system resource, the request will fail. Some 
key resources include Fast Path spinlock, the CPU mutex, and a CPU 
transition lock. 


If the $QIO or SET DEVICE/PREFERRED_CPU returns failure, you 
should consider retrying either immediately or after a short delay. It is 
possible that a large number of ports were being reassigned, and the 
request failed due to resource contention. 


The $I0_FASTPATH system service performs operations on the set of 
Fast Path devices and CPUs enabled for Fast Path use. The 
$10_FASTPATHW system service completes synchronously. That is, it 
returns after the operation is complete. 


The FP$K_BALANCE_PORTS function code specifies that the system 
service is to distribute the set of system assignable Fast Path ports across 
the intersection of a caller-supplied set of candidate CPUs. 


10.2.3. Fast Path Restrictions 


Fast Path restrictions include the following: 


e Only high-volume I/Os are optimized. 


Fast Path streamlines the operation of high-volume I/O. I/O that does not meet the definition of 


high-volume is not optimized. 
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A high-volume Fast Path I/O is a read or write operation to a Fast Path device without special I/O 
modifiers issued at a time when necessary resources have been pre-allocated and there are no 
circumstances restricting I/O operations. 


Send-credits resource must be managed for DSA controllers. 
Applications seeking maximum performance must ensure the availability of sufficient I/O resources. 


The only I/O resource that a Fast Path user needs to be concerned about is send credits. Send credits are 
extended by DSA controllers to host systems and represent the maximum number of I/Os that can be 
outstanding at any given point in time. If an application sends an unlimited number of simultaneous I/Os 
to a controller, it is likely that some I/O will back up waiting for send credits. 


You can tell whether the send-credit limit is being exceeded by using the DCL command SHOW 
CLUSTER/CONTINUOUS, followed by an ADD CONNECTIONS, CR_WAIT command. Rapidly 
increasing credit-wait counts for the disk-class driver connections (a LOC_PROC_NAME name of 
VMS$DISK_CL_DRVR) is a sign that an application may be incurring send-credit waits. 


To ensure sufficient send credits, some controllers, like the HSC and HSJ, allow the number of send 
credits to vary; however, not all controllers have this flexibility, and different controllers have different 
send-credit limits. The best workaround is to know your application access patterns and look for 
send-credit waits. 


If the number of send credits is being exhausted on one node, then add another controller to spread the 
load over multiple controllers. An alternative is to rework the application to load balance controller 
activity throughout the cluster, spreading a given controller's disk load over multiple nodes and allowing 
an application to exceed the send credits allotted to one node. 


10.2.4 Special Considerations for Fast Path on Multi-RAD Systems 


On systems supporting multiple resource affinity domains (RADs), the best performance for Fast Path ports 
is usually obtained by setting the Fast Path preferred CPU assignment to a CPU within the same RAD as the 
port. 


The FASTPATH_SERVER restricts its distribution of ports accordingly whenever possible. If a port should be 
within a RAD without available Fast Path CPUs, the system will set the preferred CPU to the primary CPU. 


Because you can override this assignment by the methods described in this chapter, care should be taken that 
reassignment does not sacrifice the performance improvements provided by localizing activity to a single 
RAD. 
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A I/O Function Codes 


This appendix lists the function codes and function modifiers defined in the $IODEF macro. The arguments 
for these functions are also listed. 


A.1 ACP-QIO Interface Driver 


This section lists the function codes and function modifiers for the ACP-QIO interface driver. 


Functions Arguments Modifiers 
I0$_CREATE P1 — FIB descriptor address IO$M_CREATE! 
1a CCuse P2— fil ing add 10$M_ACCESS! 
10$ DEACCESS — file name string address = : 
IO$_MODIFY P3 — result string length address 10$M_DELETE 
10$_DELETE 10$M_DMOUNT®? 


P4 — result string descriptor address 
P5 — attribute list address 
10$_MOUNT None None 


1. Only for IO$_CREATE and I0$_ACCESS 
2. Only for IO$_CREATE and IO$_ DELETE 
3. Only for IO$_ACPCONTROL 


10$_ACPCONTROL 


QIO Status Returns 


SS$_ACCONFLICT 
SS$_BADCHKSUM 
SS$_BADFILEVER 
SS$_BADQFILE 

SS$_DEVICEFULL 


SS$_ACPVAFUL 
SS$_BADFILEHDR 
SS$_BADIRECTORY 
SS$_BLOCKCNTERR 
SS$_DIRFULL 


SS$_BADATTRIB 
SS$_BADFILENAME 
SS$_BADPARAM 
SS$_CREATED 
SS$_DIRNOTEMPTY 


SS$_DUPDSKQUOTA 
SS$_EXBYTLM 
SS$_FCPREWNDERR 
SS$_FILELOCKED 
SS$_FILESEQCHK 
SS$_HEADERFULL 


SS$_DUPFILENAME 
SS$_EXDISKQUOTA 
SS$_FCPSPACERR 
SS$_FILENUMCHK 
SS$_FILESTRUCT 
SS$_IBCERROR 


SS$_ENDOFFILE 
SS$_FCPREADERR 
SS$_FCPWRITERR 
SS$_FILEPURGED 
SS$_FILNOTEXP 
SS$_IDXFILEFULL 
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QIO Status Returns 


SS$_ILLCNTRFUNC 
SS$_NOPRIV 
SS$_NOTAPEOP 
SS$_NOTVOLSET 
SS$_QFNOTACT 
SS$_TAPEPOSLOST 


SS$_NODISKQUOTA 
SS$_NOQFILE 
SS$_NOTLABELMT 


SS$_OVRDSKQUOTA 
SS$_SERIOUSEXCP 
SS$_TOOMANYVER 


SS$_NOMOREFILES 
SS$_NOSUCHFILE 
SS$_NOTPRINTED! 
SS$_QFACTIVE 
SS$_SUPERSEDE 
SS$_WRITLCK 


SS$_WRONGACP 


1. The second longword of the IOSB contains a job controller status code. 


A.2 Disk Drivers 


This section lists the function codes and function modifiers for the disk drivers. 


Functions Arguments Modifiers 
10$_READVBLK P1 — buffer address 10$M_INHSEEK! 
10$_READLBLK : 7 
10$ READPBLK P2 — byte count P3 — disk address 1 Des 
10$_WRITEVBLK 10$M_DELDATA 
10$_WRITELBLK 1O$M_INHRETRY 
10$_WRITEPBLK IO$M_ERASE* 
10$_WRITECHECK P1 — buffer address None 

P2 — byte count P3 — disk address 
I0$_SENSECHAR None None 
10$_SENSEMODE 
10$_PACKACK 
10$_AVAILABLE 
10$_UNLOAD 
10$_SEARCH P1 — read/write head position None 
I0$_SEEK P1 — seek to specified cylinder None 
10$ FORMAT® P1— RX02 density None 
10$_SETPRFPATH P1 — node or HSx name IO$_FORCEPATH 
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Functions Arguments Modifiers 
I10$_CREATE P1 — FIB descriptor address IO$M_CREATE 
I0$_ACCESS 5 icwawie ctaneadae I0$M_ACCESS 
10$_DEACCESS ek a ac aa 10$M_DELETE 
10$_MODIFY P3 — result string length address I0$M_DMOUNT 
10$_DELETE 


10$ ACPCONTROL P4 — result string descriptor address 


P5 — attribute list address 


1. Only for IO$_READPBLK and IO$_WRITEPBLK (not for TU58, RX01, RX02, RBO2, or RLO2) 
2. Not for RX01 and RX02 

3. Only for IO$_RWRITEPBLK on RX02 

4. Only for write functions 

5. Not for DSA disks 


QIO Status Returns 


SS$_ABORT SS$_CANCEL SS$_CTRLERR 
SS$_DATACHECK SS$_DATAOVERUN SS$_DRVERR 
SS$_FORCEDERR SS$_FORMAT SS$_ILLIOFUNC 
SS$_IVADDR SS$_IVBUFLEN SS$_MEDOFL 
SS$_NONEXDRV SS$_NORMAL SS$_OPINCOMPL 
SS$_PARITY SS$_RCT SS$_RDDELDATA 
SS$_TIMEOUT SS$_UNSAFE SS$_VOLINV 
SS$_WASECC SS$_WRITLCK 


A.3 Magnetic Tape Drivers 


This section lists the function codes and function modifiers for the magnetic tape drivers. 


Functions Arguments Modifiers 
10$_READVBLK P1— buffer address P2— [0$M DATACHECK! 
10$_READLBLK byte count 
10$_ READPBLK IO$M_INHRETRY 


I10$M_REVERSE2 


429 


1/0 Function Codes 
Magnetic Tape Drivers 


Functions 


Arguments 


Modifiers 


10$_WRITEVBLK 
10$_WRITELBLK 
10$_WRITEPBLK 


10$_SETMODE 
10$_SETCHAR 


I10$_CREATE IO$_ACCESS 


10$_DEACCESS 
10$_MODIFY 
10$_ACPCONTROL 


10$_SKIPFILE 


IO0$_SKIPRECORD 


10$_REWIND 
10$_REWINDOFF 
10$_UNLOAD 


10$_WRITEOF 


10$_SENSEMODE 
10$_SENSECHAR 


430 


P1 — buffer address 
P2 — byte count 


P1 — characteristics buffer 
address 


P2 — characteristics buffer 
length® 


P1 — FIB descriptor 
address 


P2 — file name string 
address 


P3 — result string length 
address 


P4 — result string 
descriptor address 


P5 — attribute list address 


P1 — skip n tape marks 


P1 — skip n blocks 


None 


None 


P1 — characteristics buffer 


address® 


P2 — characteristics buffer 
length® 


I0$M_DATACHECK! 
10$M_INHRETRY 


I0$M_INHEXTGAP? 
IO0$M_NOWAIT* 


IO0$M_ERASE® 


IO0$M_CREATE? 
10$M_ACCESS’ 
10$M_DMOUNT® 


I0$M_ALLOWFAST® 
10$M_INHRETRY 


IO$M_NOWAIT* 
IO$M_INHRETRY 
IO$M_NOWAIT* 
IO$M_INHRETRY 


IO$M_NOWAIT* 
10$M_RETENSION 
IO$M_INHEXTGAP? 
IO$M_INHRETRY 
IO$M_NOWAIT* 
10$M_INHRETRY 
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Functions Arguments Modifiers 


10$_DSE!° None None 


10$_PACKACK 
I0$_AVAILABLE 


. Not for TS04 and TU80 

. Not for TK50 

. Only for TE16, TU45, and TU77 

. Only for TU81-Plus drives 

. IO$M_REASE takes no arguments; only for IO$_WRITEBLK and I0$_WRITEPBLK on TMSCP 
drives. 

. Only for TMSCP drives 

. Only for IO$_CREATE and IO$_ACCESS 

. Only for IO$_ACPCONTROL 

. Only for local SCSI drives 

0.Only for TU78, TU81, TA81, and TA78 


aorRWN FH 


rFP oman oaSD 


QIO Status Returns 


SS$_ABORT SS$_CANCEL SS$_CTRLERR 
SS$_DATACHECK SS$_DATAOVERUN SS$_DEVOFFLINE 
SS$_DRVERR SS$_ENDOFFILE SS$_ENDOFTAPE 
SS$_ENDOFVOLUME SS$_FORMAT SS$_ILLIOFUNC 
SS$_MEDOFL SS$_NONEXDRV SS$_NORMAL 
SS$_OPINCOMPL SS$_PARITY SS$_SERIOUSEXCP 
SS$_TIMEOUT SS$_UNSAFE SS$_VOLINV 
SS$_WRITLCK 


A.4. Mailbox Driver 


This section lists the function codes and function modifiers for the mailbox driver. 


Functions Arguments Modifiers 
I0$_READVBLK IO$_READLBLK P1 — buffer IO0$M_NOW 
I0$_READPBLK I0$_WRITEVBLK address 10$M_NORSWAIT! 


10} WRETELBEE IO) WEEEBLE P2 — buffer size I0$M_READERCHECK! 


10$M_WRITERCHECK2 
I0$M_STREAM2 
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I/O Function Codes 
Mailbox Driver 


Functions Arguments Modifiers 


IO$_ WRITEOF None IO$M NOW 
IO$M_ READERCHECK 
IO$M_ STREAM 


IO$_SETMODE!IO$M_READATTN P1—AST address None 
10$_SETMODE!IO$M_WRTATTN p2— AST 
10$_SETMODE!IO$MB_ROOM_NOTIFY = 

parameter 


P3 — access mode 
10$_SETMODE!IO$M_READERWAIT®? None None 


10$_SETMODE!IO$M_WRITERWAIT? 


I0$_SETMODE!IO$M_SETPROT P2 — volume None 
protection mask 


10$_SENSEMODE!IO$M_READERCHECK? None None 


10$_SENSEMODE!IO$M_WRITERCHECK® 


1. Only for write functions 
2. Only for read functions 
3. VAX specific 


QIO Status Returns in RO 


SS$_ACCVIO SS$_EXQUOTA SS$_ILLIOFUNC SS$INSFMEM 
SS$MBFULL SS$_MBTOOSML SS$_NOPRIV SS$_NORMAL 


IOSB Status Returns 


SS$_ABORT SS$_BUFFEROVF SS$_CANCEL SS$_ENDOFFILE 
SS$_NOREADER SS$_NORMAL SS$_NOWRITER 
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I/O Function Codes 
Terminal Driver 


This section lists the function codes and function modifiers for the terminal driver. 


Functions 


Arguments 


Modifiers 


10$_READVBLK 
10$_READLBLK 
10$_READPROMPT 


I0$_READVBLK 


10$_WRITEVBLK 
10$_WRITELBLK 
10$_WRITEPBLK 


10$_SETMODE I0O$_SETCHAR 


10$_SETMODE I0$_SETCHAR 
10$_SETMODE 


P1 — buffer address 
P2 — buffer size 
P3 — timeout 


P4 — read terminator block 
address 


P5 — prompt string buffer 
address 


P6 — prompt string buffer 


size! 


P1 — buffer address 
P2 — buffer size 


P3 — access mode to probe 
itemlist 


P4 — (zero) 
P5 — itemlist buffer 
address 


P6 — itemlist buffer size 
P1 — buffer address 

P2 — buffer size 

P3 — (ignored) 

P4 — carriage control 
specifier® 


P1 — characteristics buffer 
address 


P2 — characteristics buffer 
size 


P3 — speed specifier 
P4 — fill specifier 
P5 — parity flags 
None 

P1 — buffer address 
P2 — buffer size 


10$M_NOECHO 
I0$M_CVTLOW 
I0$M_NOFILTR 


I0$M_TIMED IO$M_PURGE 
I0$M_DSABLMBX 
I0$M_TRMNOECHO 


IO$M_ESCAPE 


I0$M_EXTEND2 


I0$M_CANCTRLO 
I0$M_ENABLMBX 
I0$M_NOFORMAT 


I0$M_REFRESH 
I0$M_BREAKTHRU 


I0$M_HANGUP 
I0$M_BRDCST 
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I/O Function Codes 
Terminal Driver 


Functions Arguments Modifiers 


I0$_SETMODE IO$_SETCHAR P1— AST service routine IO$M_CTRLCAST 


address I10$M_CTRLYAST 
P2 — AST parameter 


P3 — access mode to deliver 
AST 


IO$_SETMODE IO$ SETCHAR  P1— AST service routine IO$M_OUTBAND 


address 
10$M_TT_ABORT* 


I0$M_INCLUDE 


P2 — character mask 
address 


P3 — access mode to deliver 


AST 
10$_SETMODE IO$_SETCHAR  P1— address of control 10$M_SET MODEM® 
signals 
IO$M_MAINT 
10$_SETMODE IO0$_SETCHAR None IO$M_LOOP® 
10$M_UNLOOP? 
IO$M_MAINT 
10$_TTY_PORT IO0$M_LT_CONNECT 
IO0$M_LT_DISCON 
10$_TTY_PORT Pi omit addvesct 10$M_LT_MAP_PORT 


P2 — queued status 


IO$ TTY PORT P1 — service name IO$M_LT RATING 
descriptor address 


P2 — service rating 

IO$ TTY PORT P1 — itemlist address IO$M_LT SENSEMODE 
P2 — itemlist length 
P3 — entity type 


P4 — entity string 
descriptor 


IO$ TTY PORT P1 — itemlist address IO$M_LT SETMODE 
P2 — itemlist length 
P3 — entity type 


P4 — entity string 
descriptor 
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Local Area Network Device Drivers 


Functions 


Arguments 


Modifiers 


10$_SENSEMODE 
10$_SENSECHAR 


10$_SENSEMODE 
10$_SENSECHAR 


10$_SENSEMODE 


P1 — characteristics buffer 
address 


P2 — characteristics buffer 
size 

P1 — address of input 
modem signal block 

P1 — buffer address 

P2 — buffer size 


I0$M_TYPEAHDCNT 


I0$M_RD_ MODEM 


I0$M_BRDCST 


1. Only for IO$_READPROMPT 
2. Only for itemlist read function. Do not specify with other modifiers. 
3. Only for IO$_WRITEBLK and IO$_WRITEVBLK 
4, Only with IO$¢M_OUTBAND 
5. Only with IO$M_MAINT 
6. Itemlist: IO$V_LT_MAP_NODENAM, IO$V_LT_MAP_PORNAM, IO$V_LT_MAP_SRVNAM, 
IO$V_LT_MAP_LNKNAM, and IO$V_LT_MAP_NETADR. 
QIO Status Returns 
SS$_ABORT SS$_BADESCAPE SS$_BADPARAM 
SS$_CANCEL SS$_CHANINTLK SS$_CONTROLC 


SS$_CONTROLO 
SS$_INCOMPAT 
SS$_PARTESCAPE 


SS$_CONTROLY 
SS$_NORMAL 
SS$_TIMEOUT 


SS$_DATAOVERUN 
SS$_PARITY 


A.6 Local Area Network Device Drivers 


This section lists the function codes and function modifiers for the local area network drivers. 


Functions 


Arguments 


Modifiers 


10$_READLBLK 
10$_READVBLK 
10$_READPBLK 
10$_WRITELBLK 
10$_WRITEVBLK 
10$_WRITEPBLK 


10$_SETMODE 
10$_SETCHAR 


P1 — buffer address 
P2 — buffer size 


10$M_NOWw?2 
10$M_RESPONSE? 


P4 — 802 format fields (optional)! 


P5 — destination address (optional)! 


P2 — extended characteristics buffer IO$M_CTRL 


(optional)* 


I0$M_STARTUP 
10$M_SHUTDOWN 
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Fast I/O Function Codes and Modifiers 


Functions Arguments Modifiers 
10$_SETMODE P1 — AST service address IO$M_ATTNAST 
108 SETCHAR P3 — access mode to deliver AST 
10$_ SENSEMODE P1 — device characteristics buffer IO$M_CTRL 
I0$_ SENSECHAR (optional) 


P2 — extended characteristics buffer 
(optional) 


1. See text for complete contents 


2. Only for read functions 
3. Only for write functions 


4. Use only with IO$M_CTRL alone or with IO$_STARTUP; that is, the set controller mode 


QIO Status Returns 


SS$_ABORT 
SS$_BUFFEROVF 
SS$_DATACHECK 
SS$_DEVALLOC 
SS$_DEVREQERR 
SS$_ENDOFFILE 
SS$_INSFMAPREG 
SS$_NOPRIV 
SS$_TIMEOUT 


SS$_ACCVIO SS$_BADPARAM 
SS$_COMMHARD SS$_CTRLERR 
SS$_DATAOVERUN SS$_DEVACTIVE 
SS$_DEVINACT SS$_DEVOFFLINE 
SS$_DISCONNECT SS$_DUPUNIT 
SS$_EXQUOTA SS$_INSFMEM 
SS$_IVBUFLEN SS$_MEDOFL 
SS$_NORMAL SS$_OPINCOMPL 
SS$_TOOMUCHDATA 


A.7 Fast I/O Function Codes and Modifiers 


This section lists the function codes and parameters for the $1O_SETUP system service. 


Functions 


Arguments 


10$_READVBLK 
10$_READLBLK 
10$_WRITEVBLK 
10$_WRITELBLK 


bufobj - user's buffer 

iosobj — I/O Status Area (IOSA) 
astadr — Completion AST routine 
flags — longword mask 


return_fandle — fandle address 
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A.8 Fast Path Function Code and Modifiers 


This section lists the function code and function modifiers for Fast Path. 


Function Argument Modifiers 
10$_SETPRFPATH P1— CPU mask I0$M_PREFERRED_CPU 
None IO$M_SYS_ASSIGNABLE 
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B 10$ DIAGNOSE Function for SCSI Class 
Drivers 


As of OpenVMS Version 7.0, the $QIO IO$_DIAGNOSE function has been enhanced to support 64-bit 
addressing for the following SCSI class drivers: GKDRIVER, DKDRIVER, and MKDRIVER. This means that 
the virtual addresses specified within the S2DGB may now be 64-bit virtual addresses if the user application 
requests it. 


The $QIO IO$_DIAGNOSE arguments are still as follows: 


Argument Use 
Pl S2DGB base address 
P2 S2DGB length 
P3 Reserved, should be 0 
P4 Reserved, should be 0 
P5 Reserved, should be 0 
P6 Reserved, should be 0 


The SCSI Diagnose Buffer (S2DGB) defined in STARLET now allows two formats, one for 32-bit addressing 
and one for 64-bit addressing. The 32-bit format is identical to the one supported on OpenVMS Alpha Version 
6.2. 
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Figure B-1 shows the 32-bit S2DGB format. Figure B-2 shows the 64-bit S2DGB format. 


Figure B-1 OpenVMS SCSI-2 Diagnose Buffer (S2DGB) 32-Bit Layout 


:2C 

Reserved :30 
Should Be Zero 34 
38 

ZK8486AG_ E 


440 
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Figure B-2 OpenVMS SCSI-2 Diagnose Buffer (S2DGB) 64-Bit Layout 


S2DGB$L_OPCODE :00 
S2DGB$L_FLAGS :04 


S2DGB$PQ_64CDBADDR :08 
S2DGB$PQ_64DATADDR 10 


S2DGB$PQ_64SENSEADDR 18 


ZK8487AG E 


A user application must specify which one of the two S2DGB formats is to be used by passing a format value 
in S2DGB$L_OPCODE. Specifically, S2DGB$L_OPCODE must be assigned a value of either OP_XCDB382 (= 
1) to request 32-bit format, or OP_XCDB64 (= 2) to request 64-bit format. Once the value of OP_XCDB64 has 
been specified, the user application is obligated to use the 64-bit S2DGB format and, in particular, to use the 
64-bit names for S2DGB fields as described below. Likewise, an opcode value of OP_XCDB32 obligates the 
user application to use the 32-bit names for the fields. 


The correct length of the structure is defined by the constant S2DGB$K_XCDB32_LENGTH (value: 
60-decimal), as well as by the constant S2DGB$K_XCDB64_LENGTH (value: 60-decimal). 


The fields in the S2DGB are in the sections that follow. Whenever a field has two different names for the 
32-bit and 64-bit cases, the 32-bit name is given first, and the 64-bit name is given after it in parentheses. 
Also, except for fields that contain addresses, all fields are unsigned longwords. 


S2DGB$L_OPCODE 


This field should contain either S2DGB$K_OP_XCDB32 or S2DGB$K_OP_XCDB64, depending on whether 
the user application intends to supply 32-bit virtual addresses or 64-bit virtual addresses, respectively, in the 
other fields of the S2DGB. 


S2DGB$L_FLAGS 
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This field should contain the bit fields shown in the following table. Note that these bit definitions start at bit 
0 and omit no bits. This is required for compatibility with the IO$_DIAGNOSE interface available in 
OpenVMS Alpha Version 6.1 and earlier. 


Table B-1 S2DGB$L_FLAGS Bit Fields 


Bit Field Description 


S2DGB$V_READ This bit should be 1 if the operation being performed is a read. If the 
operation is a write, this bit should be 0. 


S2DGB$V_DISCPRIV This bit should contain the DiscPriv bit value to be used in the 
IDENTIFY message sent with this operation. If 
S2DGB$V_TAGGED_REQ is 1, then this bit is ignored. Note that 
S2DGB$V_DISCPRIV may be ignored by some ports 
unconditionally. 


S2DGB$V_SYNCHRONOUS This bit is ignored because its value is beyond the control of the user 
in SCSI-2 drivers. 


S2DGB$V_OBSOLETE1 This bit is ignored. In previous releases, it represented the disabling 
of command retries, which is now beyond the control of the user in 
SCSI-2 drivers. 


S2DGB$V_TAGGED_REQ When this bit is 1, the operation is processed as using tagged 
command queuing and S2DGB$V_TAG should define the tag value 
to be used. When this bit is 0, the operation is processed without 
benefit of tagged command queuing. 


Note that although some ports do not support tagged command 
queuing, setting this bit to 1 will inhibit changing the values of 
S2DGB$L_32PADCNT (S2DGB$L_64PADCNT), 
S2DGB$L_32DSCTMO (S2DGB$L_64DSCTMO), and 
S2DGB$L_32PHSTMO (S2DGB$L_64PHSTMO), and will cause 
S2DGB$V_DISCPRIV to be ignored. Note also that some ports 
simulate untagged operations using appropriately tagged 
operations. If SDGB$V_TAGGED_RE@Q is 1, then this 3-bit field 
should contain one of the following coded constant values: 


S2DGB$K_SIMPLE indicates that the command is to be sent 
with the SIMPLE queue tag. 


S2DGB$K_ORDERED indicates that the command is to be sent 
with the ORDERED queue tab. 


S2DGB$K_EXPRESS indicates that the command is to be sent 
with the HEAD OF QUEUE queue tag. 


If S2DGB$V_TAGGED_REQ is 0, then this field is ignored. Ports 
that do not support tagged command queuing always ignore the 
S2DGB$V_TAG field and send all commands as untagged 
operations. 


Note that automatic contingent allegiance processing is not 
accessible through the IO$_DIAGNOSE function. Also, even 
though this is a 3-bit field, only 2 bits are currently being 
utilized. That is, the 3 constants above represent values, not bit 
positions. 
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Table B-1 S2DGB$L_FLAGS Bit Fields (Continued) 
Bit Field Description 
S2DGB$V_AUTOSENSE When this bit is 1, S2DGB$L_32SENSEADDR and 


S2DGB$L_32SENSELEN CONDITION or COMMAND 
TERMINATED status is returned, REQUEST SENSE data will be 
returned in the buffer defined by S2DGB$L_32SENSEADDR and 
S2DGB$L_32SENSELEN. 


When S2DGB$V_AUTOSENSE is 0, the buffer described by 
S2DGB$L_32SENSEADDR and S2DGB$L_32SENSELEN is 
ignored. In such cases, the class driver saves the autosense data in 
pool and returns it to the next IO$_DIAGNOSE, if and only if that 
I0$_DIAGNOSE has a REQUEST SENSE CDB. 


All other bits in S2DGB$L_FLAGS should be 0. 


S2DGB$L_32CDBADDR (S2DGB$PQ_64CDBADDR) 


This field should contain the 32-bit (or 64-bit) virtual address of the SCSI command data block (CDB) to be 
sent to the target by this IO$_DIAGNOSE operation. 


Note that S2DGB$L_832CDBADDR is a pointer to a longword, while S2DGB$PQ_64CDBADDR is a pointer to 
a quadword. 


S2DGB$L_32CDBLEN (S2DGB$L_64CDBLEN) 


This field should contain the number of bytes in the SCSI command data block (CDB) to be sent to the target 
by this IO$_DIAGNOSE operation. (Legal values: 2 to 248; however, some ports may restrict CDBs to smaller 
lengths. Recommended values: 2 to 16.) 


S2DGB$L_32DATADDR (S2DGB$PQ_64DATADDR) 


This field should contain the 32-bit (or 64-bit) virtual address of the DATAIN or DATAOUT buffer to be used 
with this SCSI operation. If the CDB being sent to the target does not use a DATAIN or DATAOUT buffer, 
then this field should be 0. 


Note that S2DGB$L_32DATADDR is a pointer to a longword, while SSDGB$PQ_64DATADDR is a pointer to 
a quadword. 


S2DGB$L_32DATLEN (S2DGB$L_64DATLEN) 


This field should contain the number of bytes in the DATAIN or DATAOUT buffer associated with this 
operation. If the CDB being sent to the target does not use a DATAIN or DATAOUT buffer, then this field 
should be 0. (Legal values: 0 to UCB$L_MAXBCNT. Recommended values: 0 to 65,536. All ports are required 
to support at least 65,536 byte data transfers. ) 


S2DGB$L_32PADCNT (S2DGB$L_64PADCNT) 


This field should contain the number of padding DATAIN or DATAOUT bytes required by this operation. If 
S2DGB$V_TAGGED_REQ is 1, then the PAD count value will not be its default value. (Legal values: 0 to the 
maximum number of bytes in a disk block on this system minus one. Current legal values: 0 to 511.) 


S2DGB$L_32PHSTMO (S2DGB$L_64PHSTMO) 


This field should contain the number of seconds that the port driver should wait for a phase transition to 
occur or for delivery of an expected interrupt. If S3DGB$V_TAGGED_REQ is 1 or this field contains a 0 or 1, 
then the current phase transition timeout setting will not be changed. (Legal values: 0 to 65,535 [about 18 
hours].) 
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S2DGB$L_32DSCTMO (S2DGB$L_64DSCTMO) 


This field should contain the number of seconds that the port driver should wait for a disconnected 
transaction to reconnect. If S2DGB$V_TAGGED_REQ is 1 or this field contains a 0 or 1, then the current 
disconnect timeout setting will not be changed. (Legal values: 0 to 65,535 [about 18 hours].) 


S2DGB$L_32SENSEADDR (S2DGB$PQ_64SENSEADDR) 


If S2DGB$V_AUTOSENSE is 1, then this field should contain the 32-bit (or 64-bit) virtual address of the 
sense buffer to be used by this SCSI operation. If S2DGB$V_AUTOSENSE is 0, this field will be ignored. 


Note that S2DGB$L_32SENSEADDR is a pointer to a longword, while S2DGB$PQ_64SENSEADDR is a 
pointer to a quadword. 


S2DGB$L_32SENSELEN (S2DGB$L_64SENSELEN) 


If S2DGB$V_AUTOSENSE is 1, then this field should contain the number of bytes in the sense buffer 
associated with this operation. (Legal values: 0 to 255. Note that a value of 0 instructs the class driver to 


discard any sense data received. Recommended value: 18. Some ports may restrict the number of sense bytes 
to 18.) If S2DGB$V_AUTOSENSE is 0, this field will be ignored. 


The following example shows how to set up a 64-bit S2DGB: 


#include /* Define S2DGB 
#include _pointers.h> /* Define VOID_PQ */ 


S2DGB diag_desc; 


/* Set up some default S2DGB descriptor values */ 


diag_desc.s2dgb$1l_opcode = OP_XCDB64 /* Use 64-bits */ 
diag_desc.s2dgb$1_flags = (S2DGBSM_READ | /* Flags*/ 

S2DGBSM_TAGGED_REQ | 

S2DGBSM_AUTOSENSE) ; 
diag_desc.s2dgbS$v_tag = S2DGBSK_SIMPLE; /* SIMPLE que tag */ 
diag_desc.s2dgb$pq_64cdbaddr = (VOID_PQ) ([0]);/* Command addr */ 
diag_desc.s2dgb$1_64cdblen = 6; /* Command length */ 
diag_desc.s2dgbSpq_64dataddr = (VOID_PQ) ([0]);/* Data addr */ 
diag_desc.s2dgb$1_64datlen = 20; /* Data length ae 
diag_desc.s2dgb$1_64padent = 0; /* Pad length * / 
diag_desc.s2dgb$1_64phstmo = 20; /* Phase timeout */ 
diag_desc.s2dgb$1_64dsctmo = 10; /* Disc timeout */ 
diag_desc.s2dgb$pq_64senseaddr = (VOID_PQ) ([0]);/* Autosense addr */ 
diag_desc.s2dgb$1_64senselen = 255; /* Sense length */ 
diag_desc.s2dgb$1_reserved_1l = 0; /* Reserved */ 


status = sysSqiow(0, target_chan, IOS_DIAGNOSE, , 0, 0, 
_desc, S2DGBSK_XCDB64_LENGTH, 0, 0, 0, 0); 
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If all arguments are valid, the class driver will invoke the necessary port functions to send the CDB, transfer 
the data, and return, save or discard sense data as defined by the input S2DGB. Upon completion, the return 
IOSB will have the following format: 


Byte count <15:0> Port VMS status :00 
SCSI status Byte count <31:16> :04 


ZK8488AGE 


The DKDRIVER, GKDRIVER, and MKDRIVER class drivers, which implement other QIO functions, might 
intermix other tagged requests with IO$_DIAGNOSE requests. The order in which requests are sent 
generally matches the order in which requests are presented to the driver. An exception to this ordering 
occurs when the driver receives REQUEST SENSE for which autosense data previously has been recovered 
and stored. In this case, the IO$_DIAGNOSE will complete immediately and no command will be sent to the 
target. 


The DKDRIVER, GKDRIVER, and MKDRIVER class drivers permit only one IO$_DIAGNOSE operation to 
be active (in the start I/O routine) at a given time, except as described in the next paragraph. However, 
applications must single thread IO$_DIAGNOSE requests to properly detect the presence of sense data and 
send the required REQUEST SENSE command. This is consistent with the VAX I0$_DIAGNOSE behavior. 
For example, if three reads are issued with no waiting and the first read gets a CHECK CONDITION, the 
sense data will be discarded by the target when the second read arrives. 


The DKDRIVER, GKDRIVER, and MKDRIVER drivers permit more than one IO$_DIAGNOSE operation to 
be active (in the start I/O routine) only when all active operations have the S27DGB$V_AUTOSENSE flag 
equal to 1. Upon encountering the first IO$_DIAGNOSE with S2DGB$V_AUTOSENSE equal to 0, the class 
driver will apply the restrictions described in the previous paragraph. 
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DEC Multinational Character Set 


C DEC Multinational Character Set and 
Terminal Escape Sequences/Modes 


This appendix includes tables for the DEC Multinational character set and for terminalescape sequences and 
modes. 


C.1 DEC Multinational Character Set 


Table C-1 lists the DEC Multinational character set. The DEC Multinational character set is an 8-bit 
character set with 256 characters. The first 128 characters in the set correspond to the ASCII character set. 
The VAX EDT Reference Manual lists the graphics for these characters and describes how to enter them from 
various types of terminals. 


Table C-1 DEC Multinational Character Set 
Hex Code oo. vo re Description 
ASCII Control Characters! 
00 000 000 NUL null character 
01 001 001 SOH start of heading (Ctrl/A) 
02 002 002 STX start of text (Ctrl/B) 
03 003 003 ETX end of text (Ctrl/C) 
04 004 004 EOT end of transmission (Ctrl/D) 
05 005 005 ENQ enquiry (Ctrl/E) 
06 006 006 ACK acknowledge (Ctrl/F) 
07 007 007 BEL bell (Ctrl/G) 
08 010 008 BS backspace (Ctrl/H) 
09 011 009 HT horizontal tabulation (Ctrl/D 
0A 012 010 LF line feed (Ctrl/J) 
0B 013 011 VT vertical tabulation (Ctrl/K) 
0C 014 012 FF form feed (Ctrl/L) 
0D 015 013 CR carriage return (Ctrl/M) 
OE 016 014 sO shift out (Ctrl/N) 
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DEC Multinational Character Set 


Table C-1 DEC Multinational Character Set (Continued) 
Hex Code pr eee pala Description 
OF 017 015 SI shift in (Ctrl/O) 
10 020 016 DLE data link escape (Ctrl/P) 
11 021 017 DC1 device control 1 (Ctrl/Q) 
12 022 018 DC2 device control 2 (Ctrl/R) 
13 023 019 DC3 device control 3 (Ctrl/S) 
14 024 020 DC4 device control 4 (Ctrl/T) 
15 025 021 NAK negative acknowledge (Ctrl/U) 
16 026 022 SYN synchronous idle (Ctrl/V) 
17 027 023 ETB end of transmission block (Ctrl/W) 
18 030 024 CAN cancel (Ctrl/X) 
19 031 025 EM end of medium (Ctrl/Y) 
1A 032 026 SUB substitute (Ctrl/Z) 
1B 033 027 ESC escape 
1C 034 028 FS file separator 
1D 035 029 GS group separator 
1E 036 030 RS record separator 
1F 037 031 US unit separator 
ASCII Special and Numeric Characters 
20 040 032 SP space 
21 041 033 ! exclamation point 
22 042 034 ' quotation marks (double quote) 
23 043 035 # number sign 
24 044 036 $ dollar sign 
25 045 037 % percent sign 
26 046 038 & ampersand 
27 047 039 ' apostrophe (single quote) 
28 050 040 ( opening parenthesis 
29 051 041 ) closing parenthesis 
2A 052 042 * asterisk 
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DEC Multinational Character Set 


Table C-1 DEC Multinational Character Set (Continued) 
Hex Code pr sas Description 
2B 053 043 + plus 
2C 054 044 ' comma 
2D 055 045 — hyphen or minus 
2E 056 046 period or decimal point 
2F 057 047 / slash 
30 060 048 0 zero 
31 061 049 1 one 
32 062 050 2 two 
33 063 051 3 three 
34 064 052 4 four 
35 065 053 5 five 
36 066 054 6 six 
37 067 055 7 seven 
38 070 056 8 eight 
39 071 057 9 nine 
3A 072 058 colon 
3B 073 059 : semicolon 
3C 074 060 < less than 
3D 075 061 = equals 
3E 076 062 > greater than 
3F 077 063 ? question mark 
ASCII Alphabetic Characters 
40 100 064 @ commercial at sign 
41 101 065 A uppercase A 
42 102 066 B uppercase B 
43 103 067 C uppercase C 
44 104 068 D uppercase D 
45 105 069 E uppercase E 
46 106 070 F uppercase F 
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DEC Multinational Character Set 


Table C-1 DEC Multinational Character Set (Continued) 
Hex Code pr sas pecan Description 
47 107 071 G uppercase G 
48 110 072 H uppercase H 
49 111 073 I uppercase I 
4A 112 074 J uppercase J 
4B 113 075 K uppercase K 
4C 114 076 L uppercase L 
4D 115 077 M uppercase M 
4E 116 078 N uppercase N 
4F 117 079 O uppercase O 
50 120 080 P uppercase P 
51 121 081 Q uppercase Q 
52 122 082 R uppercase R 
53 123 083 s uppercase S 
54 124 084 T uppercase T 
55 125 085 U uppercase U 
56 126 086 Vv uppercase V 
57 127 087 W uppercase W 
58 130 088 Xx uppercase X 
59 131 089 Y uppercase Y 
5A 132 090 Z uppercase Z 
5B 133 091 [ left bracket 
5C 134 092 \ backslash 
5D 135 093 ] right bracket 
5E 136 094 s circumflex 
5F 137 095 _ underscore 
60 140 096 grave accent 
61 141 097 a lowercase a 
62 142 098 b lowercase b 
63 143 099 c lowercase c 
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Table C-1 DEC Multinational Character Set (Continued) 
Hex Code pr eee pecan Description 
64 144 100 d lowercase d 
65 145 101 e lowercase e 
66 146 102 f lowercase f 
67 147 103 g lowercase g 
68 150 104 h lowercase h 
69 151 105 i lowercase i 
6A 152 106 j lowercase j 
6B 153 107 k lowercase k 
6C 154 108 1 lowercase | 
6D 155 109 m lowercase m 
6E 156 110 n lowercase n 
6F 157 111 () lowercase o 
70 160 112 p lowercase p 
71 161 113 q lowercase q 
72 162 114 r lowercase r 
73 163 115 s lowercase s 
74 164 116 t lowercase t 
75 165 117 u lowercase u 
76 166 118 Vv lowercase v 
77 167 119 w lowercase w 
78 170 120 x lowercase x 
79 171 121 y lowercase y 
7A 172 122 Zz lowercase z 
7B 173 123 { left brace 
7C 174 124 vertical line 
7D 175 125 } right brace (ALTMODE) 
7E 176 126 ~ tilde (ALTMODE) 
7F 177 127 DEL rubout (DELETE) 
80 200 128 — [reserved] 
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Table C-1 DEC Multinational Character Set (Continued) 
Hex Code pr pias pecan Description 
81 201 129 — [reserved] 
82 202 130 — [reserved] 
83 203 131 — [reserved] 
84 204 132 IND index 
85 205 133 NEL next line 
86 206 134 SSA start of selected area 
87 207 135 ESA end of started area 
88 210 186 HTS horizontal tab set 
89 211 137 HTJ horizontal tab set with justification 
8A 212 138 VTS vertical tab set 
8B 213 139 PLD partial line down 
8C 214 140 PLU partial line up 
8D 215 141 RI reverse index 
8E 216 142 SS2 single shift 2 
8F 217 143 SS3 single shift 3 
90 220 144 DCS device control string 
91 221 145 PU1 private use 1 
92 222 146 PU2 private use 2 
93 223 147 STS set transmit state 
94 224 148 CCH cancel character 
95 225 149 MW message waiting 
96 226 150 SPA start of protected area 
97 227 151 EPA end of protected area 
98 230 152 — [reserved] 
99 231 153 — [reserved] 
9A 232 154 — [reserved] 
9B 233 155 CSI control sequence introducer 
9C 234 156 ST string terminator 
9D 235 157 OSC operating system command 
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Table C-1 DEC Multinational Character Set (Continued) 
Hex Code pr eee pce Description 
9E 236 158 PM privacy message 
OF 237 159 APC application 
AO 240 160 — [reserved] 
Al 241 161 i inverted exclamation point 
A2 242 162 ¢ cent sign 
A838 243 163 £ pound sign 
A4 244 164 — [reserved] 
A5 245 165 ¥ yen sign 
A6 246 166 — [reserved] 
A7 247 167 § section sign 
A8 250 168 | general currency sign 
A9 251 169 © copyright sign 
AA 252 170 2 feminine ordinal indicator 
AB 253 171 << angle quotation mark left 
AC 254 172 — [reserved] 
AD 255 173 — [reserved] 
AE 256 174 — [reserved] 
AF 257 175 — [reserved] 
BO 260 176 ° degree sign 
Bl 261 177 + plus/minus sign 
B2 262 178 2 superscript 2 
B3 263 179 3 superscript 3 
B4 264 180 — [reserved] 
B5 265 181 uu micro sign 
B6 266 182 I paragraph sign, pilcrow 
B7 267 183 placeholder middle dot 
B8 270 184 — [reserved] 
B9 271 185 1 superscript 1 
BA 272 186 ° masculine ordinal indicator 
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Table C-1 DEC Multinational Character Set (Continued) 
Hex Code pr sas pcan Description 
BB 273 187 >> angle quotation mark right 
BC 274 188 1/4 fraction one-quarter 
BD 275 189 1/2 fraction one-half 
BE 276 190 — [reserved] 
BF 277 191 é inverted question mark 
Co 300 192 A uppercase A with grave accent 
C1 301 193 A uppercase A with acute accent 
C2 302 194 A uppercase A with circumflex 
C3 303 195 A uppercase A with tilde 
C4 304 196 A uppercase A with umlaut(diaeresis) 
C5 305 197 A uppercase A with ring 
C6 306 198 AE uppercase AE diphthong 
C7 307 199 C uppercase C with cedilla 
C8 310 200 E uppercase E with grave accent 
C9 311 201 E uppercase E with acute accent 
CA 312 202 1 uppercase E with circumflex 
CB 313 2038 E uppercase E with umlaut(diaeresis) 
CC 314 204 I uppercase I with grave accent 
CD 315 205 I uppercase I with acute accent 
CE 316 206 i uppercase I with circumflex 
CF 317 207 I uppercase I with umlaut(diaeresis) 
DO 320 208 — [reserved] 
D1 321 209 N uppercase N with tilde 
D2 322 210 O uppercase O with grave accent 
D3 323 211 O uppercase O with acute accent 
D4 324 212 6) uppercase O with circumflex 
D5 325 213 e) uppercase O with tilde 
D6 326 214 O uppercase O with umlaut(diaeresis) 


D7 327 215 OE uppercase OE ligature 
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Table C-1 DEC Multinational Character Set (Continued) 
Hex Code pr seas Description 
D8 330 216 0) uppercase O with slash 
D9 331 217 U uppercase U with grave accent 
DA 332 218 U uppercase U with acute accent 
DB 333 219 U uppercase U with circumflex 
DC 334 220 U uppercase U with umlaut(diaeresis) 
DD 335 221 Y uppercase Y with umlaut(diaeresis) 
DE 336 222 — [reserved] 
DF 337 223 B German lowercase sharp s 
EO 340 224 a lowercase a with grave accent 
E1 341 225 a lowercase a with acute accent 
E2 342 226 a lowercase a with circumflex 
E3 343 227 a lowercase a with tilde 
E4 344 228 a lowercase a with umlaut(diaeresis) 
E5 345 229 a lowercase a with ring 
E6 346 230 Fe) lowercase ae diphthong 
E7 347 231 ¢ lowercase c with cedilla 
E8 350 232 é lowercase e with grave accent 
E9 351 233 é lowercase e with acute accent 
EA 352 234 é lowercase e with circumflex 
EB 353 235 é lowercase e with umlaut(diaeresis) 
EC 354 236 i lowercase i with grave accent 
ED 355 237 i lowercase i with acute accent 
EE 356 238 i lowercase i with circumflex 
EF 357 239 1 lowercase i with umlaut(diaeresis) 
FO 360 240 — [reserved] 
Fl 361 241 ral lowercase n with tilde 
F2 362 242 0 lowercase o with grave accent 
F3 363 243 6 lowercase o with acute accent 
F4 364 244 i) lowercase o with circumflex 
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Table C-1 DEC Multinational Character Set (Continued) 
Hex Code pr aia pce Description 
F5 365 245 6 lowercase o with tilde 
F6 366 246 fC) lowercase o with umlaut(diaeresis) 
F7 367 247 oe lowercase oe ligature 
F8 370 248 7) lowercase o with slash 
F9 371 249 ua lowercase u with grave accent 
FA 372 250 a lowercase u with acute accent 
FB 373 251 a lowercase u with circumflex 
FC 374 252 ui lowercase u with umlaut(diaeresis) 
FD 375 253 ¥ lowercase y with umlaut (diaeresis) 
FE 376 254 — [reserved] 
FF 377 255 — [reserved] 


1. The ALTMODE and DELETE characters (decimal 125, 126, and 127) are also control characters. 


C.2 Terminal Sequences and Modes 


Table C-2 lists the valid ANSI and DIGITAL private escape sequences for terminals that have the 
TT2$M_ANSICRT, TT2$M_DECCRT, TT2$M_AVO, TT2$M_EDIT, and TT2$M_BLOCK characteristics (see 
Section 5.2.1.4). 


Table C-2 also lists assumed and selectable ANSI modes and selectable DIGITAL private modes. Only the 
names of the escape sequences and modes are listed (for more information, refer to the specific VT100-, 
VT200-, or VT300- family user's guide). Unless otherwise noted, the operation of escape sequences and modes 
is identical to the particular VT100-, VT200-, or VT300- family terminals that implement these features. 


Table C-2 Sequences and Modes 


Name Valid Parameters ANSICRT DECCRT AVO_ EDIT BLOCK! 


ANSI-Defined Escape Sequences 


CPR All x x 
CUB All x x 
CUD All x x 
CUF All x x 
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Table C-2 Sequences and Modes (Continued) 
Name Valid Parameters ANSICRT DECCRT AVO~ EDIT BLOCK! 
CUP All x x 
CUU All x x 
DSR 0,3,5,6 x x 
ED 0,1,2 x x 
EL 0,1,2 x x 
HVP All x x 
IND x x 
NEL x x 
RI x x 
RIS x x 
scs UK,ASCII,0 x 
scs UK,ASCII x x 
SGR 0,4,7 x x 
SGR 0,1,4,5,7 x 
DA Terminal specific x 
HTS x 
RM Class specific x 
SM Class specific x 
TBC 0,3 x 
DCH All x x 
DL All x x 
IL All x x 


DIGITAL Private Escape Sequences 


DECDHDL 2,3 x 
DECDWL 6 x 
DECKPAM x 
DECKPNM x 
DECRC 8 x 


DECSC 


yy 
Pa 
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Table C-2 Sequences and Modes (Continued) 
Name Valid Parameters ANSICRT DECCRT AVO~ EDIT BLOCK! 
DECSTBM All x 
DECSWL 5 x 
DECPRO 0,1,4,5,7,254 
DECTTC 0,1 


DECXMIT 5 


ANSI Selectable Modes (Set with ANSI SM/RM) 


IRM 4 x 
GATM 1 x 
ERM 6 

TTM 16 

DIGITAL Private Selectable Modes (Set with ANSI SM/RM) 

DECCKM 1 x 
DECANM 2 x 
DECCOLM 3 x 
DECSCLM 4 x 
DECSCNM 5 x 
DECOM 6 x 
DECAWM 7 x 
DECARM 8 x 
DECEDM 10 


DECEKEM 16 


DECLTM 11 

DECSCFDM 18 

DECTEM 14 

ANSI Assumed Modes 

CRM Reset Reset 

EBM Reset Reset 

ERM Set Set 2 
FEAM Reset Reset 
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Table C-2 Sequences and Modes (Continued) 
Name Valid Parameters ANSICRT DECCRT AVO~ EDIT BLOCK! 
FETM Reset Reset 
GATM N/A N/A 2 
HEM N/A N/A 
IRM Reset Reset 2 2 
KAM Reset Reset 
MATH N/A N/A 
PUM Reset Reset 
SATM N/A N/A 
SRTM Reset Reset 
TSM Reset Reset 
TTM N/A N/A 2 
VEM N/A N/A 


1. Terminal characteristics. Prefix is TT2$M_. 
2. Selectable mode. 
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D Control Connection Routines 


This appendix lists and describes the calling conventions for the pseudoterminal driver control connection 
routines. The routines appear in this section in alphabetical order. 


Table D-1 lists the control connection routines and their functions: 


Table D-1 Control Connection Routines 
Routine Name Description 
PTD$CANCEL Cancels a queued control connection read request 
PTD$CREATE Creates a pseudoterminal 
PTD$DELETE Deletes a pseudoterminal 
PTD$READ Reads data from the pseudoterminal 
PTD$READW Reads data from the pseudoterminal and waits for 
read to complete 
PTD$SET_EVENT_NOTIFICATION Enables or disables terminal event notification ASTs 
PTD$WRITE Writes data to the pseudoterminal 


D.1 PDT$CANCEL — Cancel Queued Request 


Cancels a queued control connection read request. 


D.1.1 Format 


PDTSCANCEL chan 


D.1.2 Returns 
OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


D.1.3 Arguments 


chan 


OpenVMS usage: channel 
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type: word (unsigned) 
access: read only 
mechanism: by value 


Number of the I/O channel assigned to the pseudoterminal. This channel is only intended to be sued for 
PTD$XXxX operations. 


D.1.4 Return Values 


SS$_NORMAL Normal successful completion. 

SS$_DEVOFFLINE Device is off line and request cannot 
proceed. 

SS$_IVCHAN Illegal channel. 

SS$_NOPRIV Insufficient privilege to perform request. 


D.2 PDT$CREATE — Create a Pseudoterminal 


Creates a new pseudoterminal with a unique device name. 


D.2.1 Format 


PDTSCREATE chan [,acmode] [,charbuff] [,bufflen] [,astadr] [,astprm] 
[,ast_acmode], inadr 


D.2.2 Returns 
OpenVMS usage: cond_value 


type: longword (unsigned) 
access: write only 
mechanism: by value 


D.2.3. Arguments 


chan 


OpenVMS usage: channel 


type: word (unsigned) 
access: write only 
mechanism: by value 


Number of the channel that is assigned to the new pseudoterminal. This argument is the address of a word 
into which PTD$CREATE writes the channel number. This channel is only intended to be used for PTD$XXX 
operations. 
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acmode 


OpenVMS usage: access_mode 


type: longword (unsigned) 
access: read only 
mechanism: by value 


Access mode to be associated with the channel. The most privileged access mode is the access mode of the 
caller. I/O operations on the channel can be performed only from equal and more privileged access modes. 


charbuff 

OpenVMS usage: device_characteristics 
type: longword (unsigned) 
access: read only 

mechanism: by reference 


Address of buffer containing the device characteristics. This information is used to set up the 
pseudoterminal's initial characteristics. This buffer can be 12, 16, or 20 bytes long. 


Figure D-1 shows the format of this buffer: 


Figure D-1 Device Characteristics Buffer 


Page Length Basic Terminal Characteristics 
Extended Terminal Characteristics 


ZK9573G E 


bufflen 
OpenVMS usage: word_unsigned 


type: word (unsigned) 
access: read only 
mechanism: by value 


Length of the characteristics buffer (either 12, 16, or 20 bytes). This argument is required if you supply the 
charbuff argument. 


astadr 


OpenVMS usage: ast_procedure 


type: procedure value 
access: call without stack unwinding 
mechanism: by reference 
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AST service routine to be executed when the terminal connection deassigns the last channel to the 
pseudoterminal. This argument is the procedure value of this routine. This is a repeating AST and is active 
until the control connection deletes the pseudoterminal. 

astprm 


OpenVMS usage: user_arg 


type: longword (unsigned) 
access: read only 
mechanism: by value 


AST parameter to be passed to the AST service routine specified by astadr. 


ast_acmode 


OpenVMS usage: access_mode 


type: longword (unsigned) 
access: read only 
mechanism: by value 


Access mode for which the AST is to be declared. The most privileged access mode is the access mode of the 
caller. The resulting mode is the access mode at which the AST is declared. 


inadr 


OpenVMS usage: address_range 


type: longword (unsigned) 
access: read only 
mechanism: by reference 


Address of a two-longword array containing the starting and ending virtual addresses in the virtual address 
space of the process (either PO or P1 regions) to be used as I/O buffers. The array contains, in order, the 
starting and ending virtual addresses. The addresses supplied to inadr must express an integral number of 
CPU-specific pages. The lower address must be on a CPU-specific page boundary, and the higher address 
must be one less than a CPU-specific page boundary. Together these addresses form a range from lowest to 
highest bytes. The pages must already exist and must be fully contained in either PO or P1 space. All pages in 
the range must: 


e Have identical page protection 

e Be writable in the mode of the caller 

e Be owned by the same access mode 

e Be owned in a mode equal to or less privileged than the caller 


e Be of the same page type (process or global) 


D.2.4 Description 


PTD$CREATE creates a new pseudoterminal with a unique device name. This device name is in the form 
FTAn:, where n is the unit number. 
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When a pseudoterminal is created, it inherits the current system terminal default attributes unless you 
specify an alternate set of characteristics. 


D.2.5 Return Values 


SS$_NORMAL 
SS$_ACCVIO 
SS$_BADPARAM 
SS$_EXBYTLM 


SS$_EXQUOTA 
SS$_EXASTLM 
SS$_INSFMEM 
SS$_INSFWSL 


SS$_IVSECFLG 
SS$_NOPRIV 
SS$_PAGPNWNVIO 
SS$_VA_IN_USE 


Normal successful completion. 
Unable to read one of the arguments. 
Bad Parameter Value. 


Insufficient BYTLM to create device or map 
buffers. 


Insufficient quota to create device. 
Insufficient AST quota for notification AST. 
Insufficient memory to create device. 


Insufficient working set limit to map 
buffers. 


Invalid process or global section flags. 
No privilege for attempted operation. 
Page owner violation. 


Virtual address already in use. 


D.3 PDTSDELETE — Delete a Pseudoterminal 


Forces the pseudoterminal to be deleted and frees the channel. 


D.3.1 Format 


PDTSDELETE chan 


D.3.2 Returns 


OpenVMS usage: longword (unsigned) 


type: write 


access: by value 


D.3.3 Argument 


chan 


OpenVMS usage: channel 
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type: word (unsigned) 
access: read only 
mechanism: by value 


Number of the I/O channel assigned to the pseudoterminal. This channel is only intended to be used for 
PTD$XXxX operations. 


D.3.4 Description 


PTD$DELETE forces the pseudoterminal to be deleted and frees the channel assigned to the pseudoterminal. 
When a pseudoterminal is deleted, any process using the pseudoterminal (except the control program) is 
disconnected. A PTD$DELETE request causes any pending I/O for the control program to be aborted. It 
deletes any queued event notification ASTs and returns the I/O buffers back to the application. It also causes 
the pseudoterminal unit control block (UCB) to be deleted once the reference count returns to zero. 


D.3.5 Return Values 


SS$_NORMAL Normal successful completion. 

SS$_DEVOFFLINE Device is off line and request cannot 
proceed. 

SS$_IVCHAN Illegal channel. 

SS$_NOPRIV Insufficient privilege to perform request. 


D.4 PDT$READ — Read Data from Pseudoterminal 


Reads data from the pseudoterminal. The PTD$READ routine completes asynchronously; that is, it returns to 
the caller without waiting for the data to be read. 


For synchronous completion, use the PTD$READW routine. The PTD$READW routine is identical to the 
PTD$READ routine in every way, except that PTD$READW returns to the caller after the data is read. 


D.4.1 Format 


PDTSREAD [efn], chan [.astadr] [,astprm] readbuf, readbuf_len 


D.4.2 Returns 


OpenVMS usage: longword (unsigned) 
type: write only 


access: by value 
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D.4.3 Arguments 


efn 


OpenVMS usage: ef_number 


type: longword (unsigned) 
access: read only 
mechanism: by value 


Number of the event flag to be set when PTD$READ returns the requested information. If you do not specify 
this argument, event flag 0 is used. When PTD$READ begins execution, it clears this flag. 


chan 


OpenVMS usage: channel 


type: word (unsigned) 
access: read only 
mechanism: by value 


Number of the I/O channel assigned to the new pseudoterminal. This channel is only intended to be used for 
PTD$XXX operations. 


astadr 


OpenVMS usage: ast_procedure 


type: procedure value 
access: call without stack unwinding 
mechanism: by reference 


AST service routine to be executed when PTD$READ completes. If you specify astadr, the AST routine 
executes at the same access mode as the caller of the PTD$READ routine. 


astprm 


OpenVMS usage: user_arg 


type: longword (unsigned) 
access: read only 
mechanism: by value 


AST parameter to be passed to the AST service routine specified by the astadr argument. 


readbuf 


OpenVMS usage: char_string 


type: character coded text string 
access: write only 
mechanism: by reference 
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Address of the read I/O status longword. The first character position in an I/O buffer to receive all output is 
this address plus 4. The readbuf argument must be in the range specified in the inadr argument of the 
PTD$CREATE routine; otherwise, an SS$_ACCVIO status is returned. 

readbuf_len 


OpenVMS usage: word_unsigned 


type: word (unsigned) 
access: read only 
mechanism: by value 


Number of characters that can be read from the pseudoterminal and stored in the buffer specified by 
readbuf. 


D.4.4 Description 


The PTD$READ routine reads data from the pseudoterminal. The read request completes with a minimum of 
one character and a maximum of the number of characters specified by the readbuf_len argument. The read 
operation completes when the pseudoterminal has characters to output. If a read request is issued and no 
data is available, the read request is queued and then completed at a later time. 


D.4.5 Return Values 


SS$_NORMAL Normal successful completion. 

SS$_ACCVIO Unable to read an argument, or invalid read 
buffer address. 

SS$_DEVOFFLINE Device is off line and request cannot 
proceed. 

SS$_EXASTLM Insufficient AST quota for notification AST. 

SS$_ILLEFC Illegal event flag cluster. 

SS$_INSFMEM Insufficient memory. 

SS$_IVBUFLEN Buffer size supplied is illegal. 

SS$_IVCHAN Illegal channel. 

SS$_NOPRIV Insufficient privilege to perform request. 

SS$_UNASEFC Unassociated event flag cluster. 


D.5 PDTS$READW — Read Data from Pseudoterminal and Wait 


Reads data from the pseudoterminal. The PTD$READW routine completes synchronously; that is, it returns 
to the caller after the data has been read. 
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For asynchronous completion, use the PTD$READ routine. The PTD$READ routine is identical to the 
PTD$READW routine in every way except that PTD$READ returns to the caller without waiting for the data 
to be read. 


D.5.1 Format 


PDTSREADW [efn], chan [.astadr] [,astprm] readbuf, readbuf_len 


D.6 PDT$SET_EVENT NOTIFICATION — Enable or Disable 
Terminal Event Notification ASTs 


Enables or disables a number of repeating terminal event notification ASTs. 


D.6.1 Format 


PDTSSET_EVENT_NOTIFICATION chan, astadr [,astprm] [,acmode], type 


D.6.2 Returns 


OpenVMS usage: longword (unsigned) 
type: write only 


access: by value 


D.6.3 Arguments 


chan 


OpenVMS usage: channel 


type: word (unsigned) 
access: read only 
mechanism: by value 


Number of the I/O channel assigned to the pseudoterminal. This channel is only intended to be used for 
PTD$XXX operations. 


astadr 


OpenVMS usage: ast_procedure 


type: procedure value 
access: call without stack unwinding 
mechanism: by reference 


Address of the notification AST service routine, or zero if the AST is to be canceled. 
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astprm 


OpenVMS usage: user_arg 


type: longword (unsigned) 
access: read only 
mechanism: by value 


AST parameter to be passed to the AST service routine specified by the astadr argument. 


acmode 


OpenVMS usage: access_mode 


type: longword (unsigned) 
access: read only 
mechanism: by value 


Access mode for which the AST is to be declared. The most privileged access mode is the access mode of the 
caller. The resulting mode is the access mode at which the AST is declared. 


type 

OpenVMS usage: type_longword 
type: longword (unsigned) 
access: read only 
mechanism: by value 


Value that indicates which notification AST to enable. The $PTDDEF macro defines the symbolic names 
listed in Table D-2. 


Table D-2 Symbolic Names Defined by $>TDDEF Macro 
Symbolic Name Description 
PTD$C_SEND_XON Deliver notification AST when the pseudoterminal is ready to accept 
input. This AST is not delivered if the pseudoterminal is set to NO 
HOSTSYNC. 
PTD$C_SEND_BELL Deliver notification AST when the pseudoterminal wants to stop input 


and signal it with a bell character. 


PTD$C_SEND_XOFF Deliver notification AST when the pseudoterminal wants to stop input 
and signal it with a DC3 character. 


PTD$C_STOP_OUTPUT Deliver notification AST when the pseudoterminal is stopping output. 
PTD$C_RESUME_OUTPUT Deliver notification AST when the pseudoterminal is resuming output. 


PTD$C_CHAR_CHANGED Deliver notification AST when the pseudoterminal has changed some 
device characteristic. 


PTD$C_ABORT_OUTPUT Deliver notification AST when the pseudoterminal wants to abort output. 
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Table D-2 Symbolic Names Defined by $PTDDEF Macro (Continued) 


Symbolic Name 


Description 


PTD$C_START_READ 


PTD$C_MIDDLE_READ 


PTD$C_END_READ 


PTD$C_ENABLE_READ 


PTD$C_DISABLE_READ 


Deliver notification AST when the pseudoterminal is starting an 
application's read request. This AST is delivered only if read event 
notification has been enabled. 


Deliver notification AST when the pseudoterminal has finished sending 
an application's read request prompt string. This AST is delivered only if 
read event notification has been enabled. 


Deliver notification AST when the pseudoterminal has finished an 
application's read request. This AST is delivered only if read event 
notification has been enabled. 


Enable terminal read event AST delivery. If this code is used, you cannot 
supply the astadr argument. 


Disable terminal read event AST delivery. If this code is used, you cannot 
supply the astadr argument. 


D.6.4 Description 


PTD$SET_EVENT_NOTIFICATION enables or disables the repeating terminal event notification ASTs 
listed in Table D-2. After an event notification AST is enabled, it remains in effect until it is disabled or until 


the device is deleted. 


471 


Control Connection Routines 
PDT$WRITE — Write Data to Pseudoterminal 


D.6.5 Return Values 


SS$_NORMAL Normal successful completion. 

SS$_ACCVIO Unable to read an argument, or invalid I/O 
buffer address. 

SS$_BADPARAM An astadr, astprm, or acmode argument 


was not zero when enabling or disabling 
r3ad notification. 


SS$_DEVOFFLINE Device is off line and request cannot 


proceed. 
SS$_EXASTLM Insufficient AST quota for notification AST. 
SS$_INSFMEM Insufficient memory. 
SS$_IVCHAN Illegal channel. 
SS$_NOPRIV Insufficient privilege to perform request. 


D.7 PDT$WRITE — Write Data to Pseudoterminal 


Inputs data to the pseudoterminal and reads any immediately echoed characters. 


D.7.1 Format 


PDTSWRITE chan [.astadr] [,astprm] wrtbuf, wrtbuf_len [,echobuf] 
[, echobuf_len] 


D.7.2. Returns 


OpenVMS usage: longword (unsigned) 
type: write only 


access: by value 


D.7.3. Arguments 


chan 


OpenVMS usage: channel 


type: word (unsigned) 
access: read only 
mechanism: by value 


Number of the I/O channel assigned to the new pseudoterminal. This channel is only intended to be used for 
PTD$XXX operations. 
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astadr 


OpenVMS usage: ast_procedure 


type: procedure value 
access: call without stack unwinding 
mechanism: by reference 


AST service routine to be executed when PTD$READ completes. If you specify astadr, the AST routine 
executes at the same access mode as the caller of the PTD$WRITE routine. 


astprm 


OpenVMS usage: user_arg 


type: longword (unsigned) 
access: read only 
mechanism: by value 


AST parameter to be passed to the AST service routine specified by the astadr argument. 


wrtbuf 


OpenVMS usage: char_string 


type: character coded text string 
access: write only 
mechanism: by reference 


Address of the read I/O status longword. The first character position in an I/O buffer to receive all output is 
this address plus 4. The wrtbuf argument must be in the range specified in the inadr argument of the 
PTD$CREATE routine; otherwise, an SS$_ACCVIO status is returned. 

wrtbuf_len 


OpenVMS usage: word_unsigned 


type: word (unsigned) 
access: read only 
mechanism: by value 


Number of characters to be written to the pseudoterminal. These characters appear as input to the terminal 
side of the pseudoterminal. 


echobuf 


OpenVMS usage: char_string 


type: character coded text string 
access: write only 
mechanism: by reference 


Address of the echo I/O status longword. The first character position in an I/O buffer to receive all output is 
this address plus 4. The echobuf must be in the range specified by the inadr argument of the PTD$CREATE 
routine; otherwise an SS$_ACCVIO status is returned. 


473 


Control Connection Routines 
PDT$WRITE — Write Data to Pseudoterminal 


wrtbuf_len 


OpenVMS usage: word_unsigned 


type: word (unsigned) 
access: read only 
mechanism: by value 


Number of characters that can be read from the pseudoterminal. If an echo buffer is specified, up to 
echobuf_len characters can be stored in it. 


D.7.4 Description 


PTD$WRITE inputs data to the pseudoterminal and reads any immediately echoed characters. PTD$WRITE 
allows you to specify a buffer to receive any output generated by the write; you do not need to issue a separate 
read request to read this data. 


D.7.5 Return Values 


SS$_NORMAL Normal successful completion. 

SS$_ACCVIO Unable to read an argument, or invalid read 
buffer address. 

SS$_DATALOST The terminal driver type-ahead buffer is full 
and character written was lost. 

SS$_DATEAOVERUN The terminal type-ahead buffer is getting 


full; attempts to send more data might 
result in loss of characters. 


SS$_DEVOFFLINE Device is off line and request cannot 
proceed. 

SS$_EXASTLM Insufficient AST quota for notification AST. 

SS$_INSFMEM Insufficient memory. 

SS$_IVBUFLEN Buffer size supplied is illegal. 

SS$_IVCHAN Illegal channel. 

SS$_NOPRIV Insufficient privilege to perform request. 
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magnetic tape, 109 
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Full-duplex mode, 178 
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I0$_ACPCONTROL, 57, 118 
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I0$_WRITELBLK, 94, 123, 149, 205, 373 
IO$_WRITEOF, 125 
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IO$M_ACCESS, 46, 49, 118 
IO$M_ATTNAST, 390 
IO$M_BRDCST, 216, 249 
IO$M_BREAKTHRU, 179, 205 
IO$M_CANCTRLO, 174, 206 
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IO$M_NOFORMAT, 179, 206 
IO$M_NORSWAIT, 150, 151 
IO$M_NOW, 145, 150, 151, 372 
IO$M_NOWAIT, 123, 126 
IO$M “OUTBAND, 216 
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IO$M_WRITERCHECK, 145, 155 
list of, 427 


G 

Generic SCSI class driver, 301, 316 
$QIO system service format for, 309, 313 
assigning a channel to, 309 

flow of, 304, 305 

I/O status block returned by, 310 
loading, 308 

obtaining device information from, 313 
programming example, 314, 316 
security considerations, 305 

Generic SCSI descriptor 

format of, 311, 313 


Index 


H 


Half-duplex mode, 178, 189 
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LAN, extended characteristics, 321 


480 


Index 


LAN emulation, 364 status returns, 432 

ATM network, 362 SYS$GETDVI returns, 144 

topology, 364 temporary, 141, 143 
LAN emulation client (LEC), 363 terminal/mailbox interaction, 186 
LAN emulation configuration server (LECS), 363 volume protection, 155 
LAN emulation data frame format, 342 wait for writer/reader function, 154 
LAN emulation server (LES), 363 write attention AST function, 152 
was Ethernet devices, 350 write end-of-file message function, 151 

} commands, 365 


LAT $QIO, 245 write function, 149 


LAT port driver (LTDRIVER), 169 Mailboxes See also See also Terminals, 141 
LAT SENSEMODE $QIO Function, 228 Master adapter, 113 

LAT SETMODE $QIO Function, 219 MAXBUF system parameter, 196, 200, 205 
LEMAC Ethernet devices, 351 MAXBUF system parameter See also See also 


Line terminator System parameters, 196 
terminal, 178 Message format See also See Mailboxes, 187 


: Modify file function, 51 
LTDRIVER (LAT port driver), 169 MOUNT command, 131 


Mount function, 56 


M Movefile subfunction 
Magnetic tapes calling, 53 
function codes, 429 description, 53 
status returns, 431 MSCP (mass storage control protocol) 
Magnetic tapes See also I/O functions;See ACP-QIO supported devices, 298 
interface, 109 Multinational character set See also See DEC 
Mailboxes Multinational character set, 447 
deleting” 143 “DMB32 device, 169 
eleting, evice, 
device characteristics, 144 DMF32 device, 169 
disable terminal, 189 DZ11 device, 169 
driver, 141 DZ32 device, 169 
function codes, 145, 431 
function modifiers O 
IO$M_NORSWAIT, 150, 151 OSI model. 31 
IO$M_NOW, 145, 150, 151, 153 OTTO ATM devices 361 
IO$M_READATTN, 152 Out-of-band AST, 181, 216 
IO$M_READERCHECK, 150, 151, 155 
IO$M_SETPROT, 155 P 
IO$M_STREAM, 145 . 
IO$M_WRITERCHECK, 145, 155 Seale a one is 
en oe information function, 155 PASTHRU mode, 178, 179, 194, 197 
unctions PDQ FDDI devices, 359 
IO$_READLBLK, 145 Permanent mailboxes See also See Mailboxes, 143 
IO0$_READPBLK, 145 Permanent Virtual Circuits, 362 
IO$_READVBLK, 145 PID sharing, 347 
10$_WRITELBLK, 149 Port access mode, 71 
10$_WRITEOF, 151 Port selection, 71 
10$_WRITEPBLK, 149 Pecucotrmine’ Sieg 
10$_WRITEVBLK, 149 charmeuse ea 


creating, 283 

deleting, 284 

device characteristics, 285 
driver, 283 

event notification, 287 
features, 284 

flow control, 287 

I/O buffers, 285 
programming example, 289 
reading data, 286 

using write with echo, 287 
writing data, 286 


I/O status block, 156 
list of operations, 141 
message format, 144 

terminal, 187 
message size, 141 
permanent, 141, 143 
programming examples, 158 
protection, 141, 143, 155 
read attention AST function, 152 
read function, 145 
set attention AST function, 152 
set protection function, 155 


481 


Index 


Q 
QIO API, 334 
Quota file 
transfer block, 61 
Quotas 
AST, 89, 118, 145, 152, 212 
buffered I/O, 89, 118, 145 
BYTELIM, 32 
direct I/O, 89, 118 
disk, 59, 60 
mailbox buffer, 141, 143, 145 


R 


RA6O disk, 65 
RA70 disk, 65 
RA90 disk, 65 
Radix-50 encoding, 42 
RADs support See also See Resource Affinity 
Domains support, 426 
RBO2 cartridge disk, 66 
RC25 disk, 66 
RD53 disk, 66 
RD54 disk, 66 
Read attention AST function, 152 
Read/write attributes 
ACP-QIO interface, 36 
Read/write attributes subfunction, 36 
Record attributes value, 43 
Resource Affinity Domains (RADs) support, 426 
Return key, 175 
Rewind offline function, 126 
RF30 disk, 66 
RF71 disk, 66 
RKO6 cartridge disk, 66 
RKO7 cartridge disk, 66 
RLO2 cartridge disk, 66 
RMO3 disk, 66 
RMO05 disk, 66 
RP05 disk, 67 
RP0O6 disk, 67 
RPO7 disk, 67 
RQDX8 disk controller, 65 
RTPAD component of SET HOST, 179 
RX01 console disk, 67 
RX02 diskette, 68 
RX23 diskette, 68 
RX33 diskette, 69 
RX50 diskette, 69 
RZ22 disk, 69 
RZ23 disk, 69 
RZ55 disk, 69 


Ss 
SCSI (Small Computer Systems Interface) 
$QIO interface to disk class driver, 80 
disk class driver, 79 
disks 
class driver, 79 
error recovery, 75, 79 
handling errors in audio applications, 84 
hardware compliance, 298 
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SCSI class driver, 302 
SCSI class/port architecture, 302 
SCSI command 
disabling retry, 307 
enabling retry, 312 
padding, when required, 313 
setting disconnect timeout for, 313 
setting DMA timeout for, 307, 313 
setting phase change timeout for, 307, 313 
SCSI disconnect feature 
enabling, 306 
SCSI port driver, 302 
SCSI_NOAUTO system parameter, 308 
SDI (standard disk interface), 65 
Sector translation, 76 
Seek operation, 75 
Sense tape mode function, 126 
Serial line multiplexer, 169 
Set attention AST See also See Attention AST, 152 
SET HOST facility, 179 
Set modes 
magnetic tape, 127 
mailbox, 152 
Set Mac qualifier, 391 
terminal, 208 
SET TERMINAL command, 173, 187, 194 
Setting characteristics 
magnetic tape, 127 
terminal, 208 
SGEC/TGEC Ethernet devices, 350 
Shadow set virtual unit driver, 297 
functions, 298 
hardware configurations, 298 
Shared Memory Ethernet device, 357 
SHDRIVER functions, 297 
Shelving 
determining if file is shelvable, 40 
determining if file is shelved, 40 
SII integral adapter, 64 
Skip file function, 124 
Skip sectoring, 75 
Slave formatter, 113 
Small Computer Systems Interface (SCSI) See also 
See SCSI, 67 
SS$_ ABORT return, 215, 2438, 429, 431, 435 
SS$_ACCONFLICT return, 427 
SS$_ACCVIO return, 156, 431, 435 
SS$_ACPVAFUL return, 427 
SS$_BADATTRIB return, 427 
SS$_BADCHKSUM return, 427 
SS$_BADESCAPE return, 176 
SS$_BADFILEHDR return, 427 
SS$_BADFILENAME return, 427 
SS$_BADFILEVER return, 427 
SS$_BADIRECTORY return, 427 
SS$_BADPARAM return, 347, 376, 389, 427, 435 
SS$_BADQFILE return, “427 
SS$_BLOCKCNTERR return, 427 
SS$_BUFFEROVF return, 145, 399, 431, 432, 435 
SS$ CANCEL return, 429, 431 
SS$_COMMHARD return, 435 
SS$_CONTROLC return, 216 
SS$_CREATED return, 427 


SS$_CTRLERR return, 429, 431, 435 
SS$_DATACHECK return, "429, 431, 435 
SS$_ DATAOVERUN return, 177, 372, 429, 431, 435 
SS$_DEVACTIVE, 246 
SS$_DEVACTIVE return, 243, 435 
SS$_DEVALLOC return, "435 
SS$_DEVICEFULL return, 427 
SS$_DEVINACT return, 435 
SS$_DEVOFFLINE return, 431, 435 
SS$_DEVREQERR, 246 
SS$_DEVREQERR return, 435 
SS$_DIRFULL return, 427 
SS$_DIRNOTEMPTY return, 427 
SS$_DISCONNECT return, 435 
SS$_DRVERR return, 429, 431 
SS$_ ~DUPDSKQUOTA return, 427 
SS$_DUPFILENAME return, 427 
SS$_DUPUNIT return, 435 
SS$ _ ENDOFFILE return, 125, 149, 151, 372, 427 
LAN driver status return, 435 
magnetic tape status return, 431 
mailbox status return, 431 
SS$_ ENDOFTAPE return, 431 
SS$_ENDOFVOLUME return, 125, 431 
SS$_EXBYTLM return, 427 
SS$_EXDISKQUOTA return, 427 
SS$_EXQUOTA return, 156, "431, 435 
SS$_FCPREADERR return, 427 
SS$_FCPREWNDERR return, 427 
SS$_FCPSPACERR return, 4917 
SS$_FCPWRITERR return, 427 
SS$_FILELOCKED return, 427 
SS$_FILENUMCHK return, 427 
SS$_FILEPURGED return, 427 
SS$_FILESEQCHK return, 427 
SS$_FILESTRUCT return, 427 
SS$_FILNOTEXP return, 427 
SS$_FORCEDERR return, 429 
SS$_FORMAT return, 429, 431 
SS$_HANGUP return, 181 
SS$ HEADERFULL return, A427 
SS$_IBCERROR return, 427 
SS$_ IDXFILEFULL return, 427 
SS$ ILLCNTRFUNC return, 428 
SS$_ILLIOFUNC return, 156, 243, 429, 431 
SS$_INSFMAPREG return, 435 
SS$_INSFMEM return, 156, 431, 435 
SS$_IVADDR return, 429 
SS$_IVBUFLEN return, 375, 429, 435 
SS$_MBFULL return, 142, 150, 156, 431 


SS$_MBTOOSML return, 156, 431 


SS$_MEDOFL return, 429, 431, 435 
SS$_NODISKQUOTA return, 428 


SS$_NOMORFFILES return, 428 
SS$_NONEXDRYV return, 429, 431 


SS$_NOPRIV return, 155, 156, 428, 431, 435 


SS$_NOQFILE return, 428 


SS$_NOREADER return, 431 


SS$ NORMAL return, 156, 243, 429, 431, 435 


SS$_NOSUCHFILE return, 428 


SS$_NOTAPEOP return, 428 
SS$_NOTLABELMT return, 428 


SS$_NOTPRINTED return, 428 


SS$_NOTVOLSET return, 428 
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SS$_NOWRITER return, 431 
SS$_OPINCOMPL return, 429, 431, 435 
SS$_OVRDSKQUOTA return, "428 
SS$ PARITY return, 429, 431 
SS$_PARTESCAPE return, 176, 201 
SS$_QFACTIVE return, 428 
SS$_QFNOTACT return, 428 
SS$_RCT return, 429 
SS$ RDDELDATA return, 429 
SS$ SERIOUSEXCP return, 428, 431 
SS$_SUPERSEDE return, 428 
SS$_TAPEPOSLOST return, 428 
SS$ TIMEOUT return, 198, "243, 429, 431, 435 
SS$_TOOMANYVER return, 428 
SS$_TOOMUCHDATA return, 435 
SS$_ UNSAFE return, 429, 431 
SS$_VOLINV return, 429, 431 
SS$_WASECC return, 429 
SS$_WRITLCK return, 428, 429, 431 
SS$ WRONGACP return, 428 
Standards, 330 
Switched Virtual Circuits, 362 
Synchronous SCSI data transfer mode 

enabling, 306, 312 
SYS$ASSIGN routine, 141, 186, 244 
SYS$CREMBX system service, 141 
SYS$DASSGN routine, 143 
SYS$DELMBX system. service, 143 
SYS$DISMOU system service, 59 
SYS$GETDVI routine, 115 

disk, 87 

LAN drivers, 366 

mailbox, 144 

SCSI generic class driver, 313 

terminal, 188 
SYS$QIO routines 

format for request to SCSI generic class driver, 309 
SYS$QIO system service 

interface to audio functions, 80 
SYSGEN (System Generation utility) See also See 

System Generation utility, 308 

System 

console terminal, 169 
System Generation utility (SYSGEN) 

configuring SCSI devices, 308 


T 


Tabs 
Ctrl/I, 175 
terminal mechanical, 189 
terminal tab stops, 205 
Tape class drivers 
disabling the loading of, 308 
Tape files 
attributes, 114 
Tape marks, 122, 124, 125 
Tapes 
ACP control function, 57, 118 
ACP create file operation, 49 
available function, 131 
BOT marker, 124, 125 
byte count 
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read, 122 
write, 123 

data check, 114, 122, 123 

data security erase function, 130 

density, 129 

device characteristics for, 115 

driver, 109 

end-of-volume detection, 125 

EOF status, 122 

EOT marker, 124 
status, 122, 123, 125 

error recovery, 114 

extended characteristics, 116 

features, 112 

function codes, 117, 118 

function modifiers 
IO$M_DATACHECK, 114, 122, 123 
IO$M_ERASE, 123 
IO$M_INHEXTGAP, 115 
IO$M_INHRETRY, 115 
IO$M_NOWAIT, 123, 126 
IO$M_REVERSE, 122 

I/O functions, 117 
arguments, 120 
IO$_ACCESS, 118 
I0$_ACPCONTROL, 58, 118 
I0$_AVAILABLE, 131 
I0$_CREATE, 118 
I0$_DEACCESS, 118 
IO$_DSE, 118, 130 
IO$_FLUSH, 118 
I0$_MODIFY, 118, 130 
IO$_PACKACK, 131 
I0$_READLBLK, 122 
IO0$_READPBLK, 122 
IO$_READVBLK, 122 
IO$_REWIND, 123 
I0$_REWINDOFF, 126 
I0$_SENSEMODE, 126 
IO0$_SETCHAR, 127 
I0$_SETMODE, 127 
I10$_SKIPFILE, 124 
I0$_SKIPRECORD, 124 
I0$_UNLOAD, 126 
I10$_WRITELBLK, 123 
IO$_WRITEOF, 125 
I0$_WRITEPBLK, 123 
10$_WRITEVBLK, 123 

I/O status block, 131 

master adapters, 113 

modify function, 130 

pack acknowledge function, 131 

parity, 129 

positioning, 58 

programming example, 132 

quotas, 118 

read function, 122 

read reverse function, 122 

rewind function, 123 
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rewind offline function, 126 
sense mode function, 126 
set characteristics function, 127 
set mode function, 127, 129 
skip file function, 124 
skip record function, 124 
slave formatter, 113 
status returns, 118 
streaming tape systems, 115 
supported devices, 109 
SYS$GETDVI returns, 115 
tape controllers, 109 
tape mark, 122, 124, 125 
thrashing, 115 
TMSCP magnetic tapes, 109 
unload function, 126 
write end-of-file function, 125 
write function, 123 
Temporary mailboxes, 143 
Terminal characteristics, 188, 189, 194 
Terminals 
ANSI CRT terminal, 191 
autobaud detection, 187, 191 
baud rates, 187, 191, 210 
bell (Ctrl/G), 177 
broadcast messages, 186, 190, 191, 216 
carriage control, 206 
command line editing, 172, 205 
command recall (Ctrl/B), 172, 174 
control and data signals, 184 
control characters, 172, 175, 178, 196 
numeric values, 447 
control key sequences, 176 
cursor movement, 172, 174, 190 
delete character, 172 
delete line (Ctrl/U), 173, 196 
device characteristics, 188, 189, 194 
categories, 194 
changing, 211 
extended, 194 
dialup 
characteristic, 190 
lines, 181, 192, 212 
support, 181 
Digital CRT terminal, 192 
discard output (Ctrl/O), 174, 196, 206 
driver, 169 
duplex modes, 178, 181 
enable Ctrl/C AST, 212 
enable Ctrl/Y AST, 212 
escape sequences, 176, 249 
ANSI, 456 
Digital private, 456 
overflow size (item code), 201 
extended characteristics, 194 
fallback conversion, 179, 193, 212 
features, 171 
form feed, 189, 205 
frame size, 211 


function codes, 196, 433 

function modifiers 
IO$M_BRDCST, 216, 249 
IO$M_BREAKTHRU, 179, 205 
IO$M_CANCTRLO, 174, 206 
IO$M_CTRLCAST, 212 
IO$M_CTRLYAST, 174, 181, 212 
IO$M_CVTLOW, 197 
I0$M_DSABLMBX, 197 
IO$M_ENABLMBX, 206 
IO$M_ESCAPE, 176, 197 
IO$M_EXTEND, 197, 199 
IO$M_HANGUP, 212 
IO$M_INCLUDE, 188, 212, 216 
IO$M_LOOP, 215 
IO$M_LT_CONNECT, 218 
IO$M_LT_DISCON, 218 
I0$M_LT_SENSEMODE, 218 
I0$M_LT_SETMODE, 218 
IO$M_MAINT, 213, 215 
IO$M_NOECHO, 178, 179, 193, 197 
IO$M_NOFILTR, 197 
IO$M_NOFORMAT, 179, 206, 215 
IO0$M_OUTBAND, 216 
IO$M_PURGE, 197 
I0$M_RD_MODEM, 247 
IO$M_REFRESH, 206 
IO0$M_SET_MODEM, 213 
IO$M_TIMED, 198 
IO0$M_TRMNOECHO, 198 
IO$M_TT_ABORT, 188, 216 
IO$M_TYPEAHDCNT, 247 
I0$M_UNLOOP, 216 

hangup, 181, 185, 186, 193, 212, 246 

I/O functions 
CTDRIVER, 205 
IO0$_READLBLK, 196 
I0$_READPROMPT, 196 
IO0$_READVBLK, 196 
I0$_SENSECHAR, 246 
I0$_SENSEMODE, 246 
I0$_SETCHAR, 208 
I0$_SETMODE, 208 
I10$_TTY_PORT, 218 
IO0$_WRITELBLK, 205 
I0$_WRITEPBLK, 205 
IO0$_WRITEVBLK, 205 

I/O status block, 249 

initiate login, 178 

input processing, 172 

insert/overstrike (Ctrl/A), 172, 175 

interrupt (Ctrl/Y), 174 

item codes, 200 

itemlist read, 199 
item codes, 200 
item descriptor, 200 

LAT line, 169 

LAT port driver, 217 
application services creation, 244 


I/O functions, 218 
LAT rejection codes, 251 
line editing, 172, 193 
line feed, 205 
line terminators, 178 
mailbox, 186, 206 
message format, 187 
message types, 186 
modem 
characteristic, 189 
control signals, 184 
data signals, 184 
protocol, 181 
sense signals, 247 
signal control, 181 
modem signal control, 181 
no type-ahead, 190 
out-of-band 
characters, 188 
output 
CTDRIVER, 179 
RTPAD, 179 
SET HOST, 179 
output formatting, 179, 194 
output processing, 178 
page length and width, 210, 247 
parity flag, 210 
PASTHRU mode, 178, 179, 194, 197 
process preservation, 185 
programming examples, 252 
protocol, 181 
read function, 196, 205 
read verify, 175, 204 
receive speed, 210 
redisplay data (CtrI/R), 175, 196 
ReGIS graphics, 194 
restart data (Ctrl/Q), 175 
sense characteristics function, 246 
sense mode function, 246 
serial line multiplexer, 169 
set characteristics function, 208 
arguments, 209 
set mode function, 208 
arguments, 209 
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SET TERMINAL DCL command, 173, 187, 194 


SIXEL graphics, 194 
special operating modes, 178 
status (Ctrl/T), 175 
status returns, 435 
stop data (Ctrl/S), 175 
supported devices, 169 
SYS$GETDVI returns, 188 
system password, 194 
tab 

Ctri/l, 175 

mechanical, 189 

stops, 205 
terminator mask, 198, 199 
time (Ctrl/T), 175 
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transmit speed, 210 
TTY_DIALTYPE system parameter, 181, 184, 185 
type-ahead, 177, 186, 189, 247 
alternate buffer, 190 
unsolicited data, 186 
write breakthrough function, 206 
write function, 205, 207 
XON/XOFF control, 194 
Terminals See also line editing;See also Terminals, 
item codes, 172 
Terminals See also out-of-band;See also Out-of-band 
AST, 181 
Terminator character bit mask, 198 
ThinWire, 330 
Thrashing magnetic tape, 115 
Timeout periods 
for SCSI device, 307, 313 
TMS380 Token ring devices, 360 
Token Ring 
Address mappings, 337 
definition, 317 
function address mapping, 337 
LAN devices, 359 
Translations 
logical to physical, 76 
Truncate subfunction, 35 
TU58 magnetic tapes See also See Disks, 69 
Tulip Ethernet and Fast Ethernet devices, 353 
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UDAS0 disk adapter, 63 
Unload function 

disk, 96 

magnetic tape, 126 
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VAX LAN devices, 320 
VCI API, 335 


WwW 
Write attention AST function, 152 
Write breakthrough function, 206 
Write end-of-file function 
magnetic tape, 126 
message, 151 
Write protection 
hardware, 298 


x 
XQP (extended QIO processor), 21 
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